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 isv9.2.
- Core concepts
- Data model:
pbita_flowexecution - How to call the Custom APIs
- Reference for all 8 Custom APIs
- Fallback flow
Util_Log_Write - Troubleshooting and operational notes
- Appendices
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 returnSuccess = falseand trace the error internally. pbita_ValidateAndUpsertis 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.
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 to1/2/3is handled internally (see Appendix B).
For Actions, use the Microsoft Dataverse → Perform an unbound action step:
- Action name: type the unique name, e.g.
pbita_WriteFlowLog. - Fill in the displayed parameters (names are case sensitive).
- 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.
- 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-8Use 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"];Parameter type legend: String, Integer, DateTime, Boolean. (req) = required · (opt) = optional.
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"];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
LogsJsonusing thestring(...)function on an array, or compose the JSON text and pass it to theLogsJsonparameter.
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=24C# SDK
var req = new OrganizationRequest("pbita_GetFlowHealth");
req["FlowName"] = "OrderSync";
req["SinceHours"] = 24;
var resp = service.Execute(req);
int errors = (int)resp.Results["ErrorCount"];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.
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 asCorrelationIdto all subsequentpbita_WriteFlowLogcalls.
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"];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"];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
Statusvalue other than Success/Error/Warning, the action fails with an explicit message: handle the error in the catch branch of your flow/code.
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, withpbita_timestamp = utcNow()and mapping ofstatus(text) to thepbita_statuschoice (Error→2,Warning→3, otherwise1). - Connection reference:
pbita_UtilLogWriteDataverse(Microsoft Dataverse).
After import, you must:
- Associate the connection reference
pbita_UtilLogWriteDataversewith a valid Dataverse connection. - 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. UseUtil_Log_Writeas a fallback or for purely no-code scenarios.
| 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) useNoLock.
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.)
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) |
| 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 |