Skip to content
pborg-mcPublic

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 

Repository files navigation

PowerLog — Developer Reference Guide

Reference guide for makers and consumers who need to call the PowerLog logging solution from Power Automate flows, the Web API, or .NET code.

  • Log table: pbita_flowexecution
  • Custom APIs: 8 messages (binding Global, not bound to any table)

In this document, the environment URL is abbreviated as {{url}} = https://pbita-power-log-dev.crm.dynamics.com. The Web API version used is v9.2.


Table of Contents

  1. Core concepts
  2. Data model: pbita_flowexecution
  3. How to call the Custom APIs
  4. Reference for all 8 Custom APIs
  5. Fallback flow Util_Log_Write
  6. Troubleshooting and operational notes
  7. Appendices

1. Core concepts

Action vs Function. Every Custom API is either an Action or a Function:

  • Action (write/operation): invoked via POST. From Power Automate, use the Perform an unbound action step of the Microsoft Dataverse connector.
  • Function (read-only): invoked via GET. From the Web API using parenthesis syntax; parameters do not modify data.

Execution context. APIs that write/read logs operate under the system context (system user): they do not depend on the caller's privileges on the pbita_flowexecution table.

Error behavior.

  • Logging actions (pbita_WriteFlowLog, pbita_WriteBatchLog, pbita_PurgeOldLogs) are non-blocking: they do not raise exceptions to the caller; on failure they return Success = false and trace the error internally.
  • pbita_ValidateAndUpsert is blocking: on validation failure it returns an error (InvalidPluginExecutionException).

Private API. pbita_PurgeOldLogs is marked as private: it is intended for internal/maintenance use and does not appear in the public list of messages.


2. Data model: pbita_flowexecution

Plural name (EntitySet) for the Web API: pbita_flowexecutions.

Column (Display) Logical name Type Required Notes
Flow Name pbita_flowname Text (200) Yes Primary column
Step Name pbita_stepname Text (200) Yes
Status pbita_status Choice Yes 1=Success, 2=Error, 3=Warning
Message pbita_message Multiline text (4000) No
Correlation ID pbita_correlationid Text (100) No Links steps of the same execution
Timestamp pbita_timestamp Date/time (UTC) Yes Time Zone Independent behavior
Duration (ms) pbita_durationms Integer No Step duration in milliseconds

Choice pbita_status — explicit values:

Value Label
1 Success
2 Error
3 Warning

In the Custom APIs, status is passed as a string ("Success", "Error", "Warning"); the mapping to 1/2/3 is handled internally (see Appendix B).


3. How to call the Custom APIs

3.1 Power Automate

For Actions, use the Microsoft Dataverse → Perform an unbound action step:

  1. Action name: type the unique name, e.g. pbita_WriteFlowLog.
  2. Fill in the displayed parameters (names are case sensitive).
  3. Outputs (Success, LogId, …) are available in subsequent steps.

For Functions (read-only), use the same unbound action step if it appears in the list, or call them via Web API (GET) with the HTTP with Microsoft Entra ID (pre-authorized) action.

3.2 Web API (REST)

  • Action → POST {{url}}/api/data/v9.2/<ApiName> with a JSON body containing the parameters.
  • Function → GET {{url}}/api/data/v9.2/<ApiName>(Param=@p)?@p=<value> (strings must be in single quotes).

Common headers:

Authorization: Bearer <token>
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Content-Type: application/json; charset=utf-8

3.3 C# SDK (IOrganizationService)

Use OrganizationRequest with RequestName set to the API name; parameters are set via the indexer and outputs are read from response.Results.

var req = new OrganizationRequest("pbita_WriteFlowLog");
req["FlowName"] = "OrderSync";
req["StepName"] = "Start";
req["Status"]   = "Success";
var resp = service.Execute(req);
bool ok = (bool)resp.Results["Success"];

4. Reference for all 8 Custom APIs

Parameter type legend: String, Integer, DateTime, Boolean. (req) = required · (opt) = optional.


4.1 pbita_WriteFlowLog — Action

Writes one log row to pbita_flowexecution. Non-blocking.

Request

Parameter Type Required Description
FlowName String req Flow name
StepName String req Step name
Status String req Success / Error / Warning
Message String opt Free-form message
CorrelationId String opt Correlation ID
DurationMs Integer opt Duration in ms
Timestamp DateTime opt Default: utcNow

Response

Property Type Description
Success Boolean true if the row was created
LogId String GUID of the created row (empty if not created)

Power Automate — Perform an unbound action → Action name pbita_WriteFlowLog, then fill in FlowName, StepName, Status, etc.

Web API

POST {{url}}/api/data/v9.2/pbita_WriteFlowLog
Content-Type: application/json

{
  "FlowName": "OrderSync",
  "StepName": "ReadOrders",
  "Status": "Success",
  "Message": "Read 42 orders",
  "CorrelationId": "OrderSync-3f9a1c",
  "DurationMs": 1280,
  "Timestamp": "2026-06-22T10:15:00Z"
}

C# SDK

var req = new OrganizationRequest("pbita_WriteFlowLog");
req["FlowName"] = "OrderSync";
req["StepName"] = "ReadOrders";
req["Status"]   = "Success";
req["Message"]  = "Read 42 orders";
req["CorrelationId"] = "OrderSync-3f9a1c";
req["DurationMs"] = 1280;
req["Timestamp"]  = DateTime.UtcNow;
var resp = service.Execute(req);
var logId = (string)resp.Results["LogId"];

4.2 pbita_WriteBatchLog — Action

Writes multiple log rows from a JSON array. Non-blocking: tracks successes and failures per individual row.

Request

Parameter Type Required Description
LogsJson String req JSON array of log entries (see schema below)

Schema of each LogsJson entry (properties in camelCase):

[
  {
    "flowName": "OrderSync",
    "stepName": "ReadOrders",
    "status": "Success",
    "message": "ok",
    "correlationId": "OrderSync-3f9a1c",
    "durationMs": 1280,
    "timestamp": "2026-06-22T10:15:00Z"
  },
  { "flowName": "OrderSync", "stepName": "Validate", "status": "Warning" }
]

Response

Property Type Description
Success Boolean true if no row failed
CreatedCount Integer Rows created
FailedCount Integer Rows not created

Web API

POST {{url}}/api/data/v9.2/pbita_WriteBatchLog
Content-Type: application/json

{ "LogsJson": "[{\"flowName\":\"OrderSync\",\"stepName\":\"ReadOrders\",\"status\":\"Success\"}]" }

C# SDK

var req = new OrganizationRequest("pbita_WriteBatchLog");
req["LogsJson"] = "[{\"flowName\":\"OrderSync\",\"stepName\":\"ReadOrders\",\"status\":\"Success\"}]";
var resp = service.Execute(req);
int created = (int)resp.Results["CreatedCount"];

In Power Automate you can build LogsJson using the string(...) function on an array, or compose the JSON text and pass it to the LogsJson parameter.


4.3 pbita_GetFlowHealth — Function

Aggregates logs from a recent time window and returns counts by status. Reads with NoLock and pagination of 5000.

Request

Parameter Type Required Description
FlowName String opt Filters on a single flow; if omitted, all flows
SinceHours Integer opt Time window in hours (default 24)

Response

Property Type Description
TotalCount Integer Total rows in the window
SuccessCount Integer Rows with Success status
ErrorCount Integer Rows with Error status
WarningCount Integer Rows with Warning status
HealthJson String JSON summary

Web API

GET {{url}}/api/data/v9.2/pbita_GetFlowHealth(FlowName=@p1,SinceHours=@p2)?@p1='OrderSync'&@p2=24

C# SDK

var req = new OrganizationRequest("pbita_GetFlowHealth");
req["FlowName"]   = "OrderSync";
req["SinceHours"] = 24;
var resp = service.Execute(req);
int errors = (int)resp.Results["ErrorCount"];

4.4 pbita_PurgeOldLogs — Action · private

Deletes rows older than the specified threshold. Non-blocking. Private API (internal/maintenance use).

Request

Parameter Type Required Description
OlderThanDays Integer req Deletes rows older than N days

Response

Property Type Description
Success Boolean Operation outcome
DeletedCount Integer Rows deleted

Web API

POST {{url}}/api/data/v9.2/pbita_PurgeOldLogs
Content-Type: application/json

{ "OlderThanDays": 90 }

C# SDK

var req = new OrganizationRequest("pbita_PurgeOldLogs");
req["OlderThanDays"] = 90;
var resp = service.Execute(req);
int deleted = (int)resp.Results["DeletedCount"];

Since it is private, it may not appear in the list of unbound actions in Power Automate. Call it via Web API or code, typically from a scheduled maintenance process.


4.5 pbita_StartCorrelation — Function

Generates a new Correlation ID to propagate through subsequent logs. Does not access data.

Request

Parameter Type Required Description
Prefix String opt Prefix (e.g. flow name) prepended to the ID

Response

Property Type Description
CorrelationId String New correlation ID

Web API

GET {{url}}/api/data/v9.2/pbita_StartCorrelation(Prefix=@p)?@p='OrderSync'

(To omit it: GET {{url}}/api/data/v9.2/pbita_StartCorrelation().)

C# SDK

var req = new OrganizationRequest("pbita_StartCorrelation");
req["Prefix"] = "OrderSync";
var resp = service.Execute(req);
string corr = (string)resp.Results["CorrelationId"];

Typical pattern: at the start of the flow, call pbita_StartCorrelation, save the output, and pass it as CorrelationId to all subsequent pbita_WriteFlowLog calls.


4.6 pbita_GetExecutionTrace — Function

Returns all logs sharing the same CorrelationId, ordered by timestamp. Reads with NoLock and pagination of 5000.

Request

Parameter Type Required Description
CorrelationId String req Correlation ID to trace

Response

Property Type Description
StepCount Integer Number of steps found
TraceJson String Ordered JSON array of steps

Web API

GET {{url}}/api/data/v9.2/pbita_GetExecutionTrace(CorrelationId=@c)?@c='OrderSync-3f9a1c'

C# SDK

var req = new OrganizationRequest("pbita_GetExecutionTrace");
req["CorrelationId"] = "OrderSync-3f9a1c";
var resp = service.Execute(req);
string trace = (string)resp.Results["TraceJson"];

4.7 pbita_ResolveLookupByName — Function

Resolves the ID of a row in any table by searching on the value of a text attribute. Reads with NoLock, returns only the first match.

Request

Parameter Type Required Description
EntityName String req Logical name of the table
AttributeName String req Attribute to search on
Value String req Value to match

Response

Property Type Description
Found Boolean true if found
Id String GUID of the row (empty if not found)

Web API

GET {{url}}/api/data/v9.2/pbita_ResolveLookupByName(EntityName=@e,AttributeName=@a,Value=@v)?@e='account'&@a='name'&@v='Contoso'

C# SDK

var req = new OrganizationRequest("pbita_ResolveLookupByName");
req["EntityName"]    = "account";
req["AttributeName"] = "name";
req["Value"]         = "Contoso";
var resp = service.Execute(req);
bool found = (bool)resp.Results["Found"];
string id  = (string)resp.Results["Id"];

4.8 pbita_ValidateAndUpsert — Action · blocking

Validates the inputs and status, then creates or updates a log row identified by (CorrelationId, StepName). Unlike the other logging actions, this one raises an error if validation fails (missing required fields or invalid status).

Request

Parameter Type Required Description
FlowName String req Flow name
StepName String req Step name (upsert key)
Status String req Success / Error / Warning
Message String opt Free-form message
CorrelationId String opt Upsert key; if present, enables in-place update
DurationMs Integer opt Duration in ms
Timestamp DateTime opt Default: utcNow

Response

Property Type Description
LogId String GUID of the created/updated row
Created Boolean true if created, false if updated

Web API

POST {{url}}/api/data/v9.2/pbita_ValidateAndUpsert
Content-Type: application/json

{
  "FlowName": "OrderSync",
  "StepName": "Validate",
  "Status": "Warning",
  "CorrelationId": "OrderSync-3f9a1c",
  "Message": "2 orders with no customer"
}

C# SDK

var req = new OrganizationRequest("pbita_ValidateAndUpsert");
req["FlowName"]      = "OrderSync";
req["StepName"]      = "Validate";
req["Status"]        = "Warning";
req["CorrelationId"] = "OrderSync-3f9a1c";
req["Message"]       = "2 orders with no customer";
var resp = service.Execute(req);
bool created = (bool)resp.Results["Created"];

If you pass a Status value other than Success/Error/Warning, the action fails with an explicit message: handle the error in the catch branch of your flow/code.


5. Fallback flow Util_Log_Write

Cloud flow (in Draft state after import) designed as a connector-based alternative to the Custom APIs, useful when you cannot or do not want to call the plugin directly.

  • Trigger: When an HTTP request is received — inputs: flowname, stepname, status, message, correlationid.
  • Action: Dataverse Add a new row to pbita_flowexecution, with pbita_timestamp = utcNow() and mapping of status (text) to the pbita_status choice (Error→2, Warning→3, otherwise 1).
  • Connection reference: pbita_UtilLogWriteDataverse (Microsoft Dataverse).

After import, you must:

  1. Associate the connection reference pbita_UtilLogWriteDataverse with a valid Dataverse connection.
  2. Activate the flow (change it from Draft to Active).

For most scenarios, prefer pbita_WriteFlowLog (Custom API): it is more direct and does not require managing a connection. Use Util_Log_Write as a fallback or for purely no-code scenarios.


6. Troubleshooting and operational notes

Symptom Likely cause Solution
Success = false from WriteFlowLog/WriteBatchLog Write-side error (intercepted, non-blocking) Check Plugin Trace Logs; verify the values being sent
Error "Status must be one of Success, Error or Warning" pbita_ValidateAndUpsert called with invalid status Pass exactly Success / Error / Warning
pbita_PurgeOldLogs does not appear in Power Automate It is a private API Call it via Web API or code
Web API Function returns 400 Bad Request Incorrect parameter syntax Use single quotes for strings and @p aliases (e.g. (FlowName=@p)?@p='X')
Parameter "not recognized" Names are case sensitive Use exactly FlowName, StepName, Status, …
Timestamp is off Time Zone Independent behavior Always send the time in UTC (ISO 8601, e.g. 2026-06-22T10:15:00Z)
Incomplete reads on large volumes — Functions already read with pagination 5000 and NoLock; no action required

Behavioral summary

  • Non-blocking (do not raise exceptions): WriteFlowLog, WriteBatchLog, PurgeOldLogs.
  • Blocking (can raise exceptions): ValidateAndUpsert.
  • Reads (GetFlowHealth, GetExecutionTrace, ResolveLookupByName) use NoLock.

7. Appendices

Appendix A — Parameter type codes (Custom API)

Parameter types used in this solution (reference CustomApiFieldType):

Code Type
0 Boolean
1 DateTime
7 Integer
10 String

(Other existing values: 2 Decimal, 3 Entity, 4 EntityCollection, 5 EntityReference, 6 Float, 8 Money, 9 Picklist, 11 StringArray, 12 Guid.)

Appendix B — Status mapping

The Custom APIs accept status as a string and convert it to the pbita_status choice:

Input (case-insensitive) Choice value
Success, 1 1
Error, Failed, Failure, 2 2
Warning, Warn, 3 3
(any other / empty) 1 (Success)

Appendix C — Quick reference

Custom API Type Blocking Private
pbita_WriteFlowLog Action No No
pbita_WriteBatchLog Action No No
pbita_GetFlowHealth Function — No
pbita_PurgeOldLogs Action No Yes
pbita_StartCorrelation Function — No
pbita_GetExecutionTrace Function — No
pbita_ResolveLookupByName Function — No
pbita_ValidateAndUpsert Action Yes No

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors