Events
Mar 31, 11 PM - Apr 2, 11 PM
The ultimate Microsoft Fabric, Power BI, SQL, and AI community-led event. March 31 to April 2, 2025.
Register todayThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
Developers can add desktop flows functionality to their applications, including programmatically triggering and canceling desktop flows. These capabilities are offered as part of the Microsoft Dataverse platform.
Important
In this article, you must replace all squared brackets [...] in URLs and input/output data with values specific to your scenario.
All desktop flows scripts are in Dataverse as part of the workflow entity.
Filter the list of workflows based on the category to identify desktop flows.
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name HTTP/1.1
{
"@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#workflows(name,workflowid)",
"value": [
{
"@odata.etag": "W1069462",
"name": "Desktop flow 1",
"workflowid": "f091ffab-58bb-4630-a115-659453d56f59",
},
{
"@odata.etag": "W1028555",
"name": "Desktop flow 2",
"workflowid": "eafba1a2-e8d4-4efa-b549-11d4dfd9a3d1",
}
]
}
If you need to retrieve the flow schema for inputs and/or outputs, you can use the clientData field for the target workflow.
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/inputs/$value HTTP/1.1
{
"schema": {
"properties": {
"inputText": {
"default": "",
"description": "",
"format": null,
"title": "inputText",
"type": "string",
"value": ""
},
"inputInteger": {
"default": "",
"description": "",
"format": null,
"title": "inputInteger",
"type": "number",
"value": "0"
}
},
"type": "object"
}
}
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/workflows([Workflow Id])/outputs/$value HTTP/1.1
{
"schema": {
"properties": {
"outputText": {
"default": "",
"description": "",
"format": null,
"title": "outputText",
"type": "string",
"value": null
},
"outputInteger": {
"default": "",
"description": "",
"format": null,
"title": "outputInteger",
"type": "number",
"value": null
}
},
"type": "object"
}
}
Dataverse stores all desktop flow runs in the flowsession entity.
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])?$select=statuscode,statecode,startedon,completedon HTTP/1.1
{
"@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#flowsessions(statuscode,statecode,startedon,completedon)/$entity",
"@odata.etag": "W1276122",
"statuscode": 8,
"statecode": 0,
"startedon": "2022-06-16T12:54:40Z",
"completedon": "2022-06-16T12:57:46Z",
}
If the desktop flow has outputs, you can query the outputs field to retrieve them.
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
GET https://[Organization URI]/api/data/v9.2/flowsessions([Flow session ID])/outputs/$value HTTP/1.1
{
"Output1": "My output value"
}
By using Dataverse, you can add the functionality of triggering a desktop flow through your application. To implement this functionality, you need to use the RunDesktopFlow action.
To call the action, you'll need the following information.
The ID
of the desktop flow that you want to run. You can get this ID via the API as the List available desktop flows section outlines earlier in this article.
Tip
Alternatively, you can retrieve the ID manually from the desktop flow details URL in Power Automate. The URL format is: https://make.powerautomate.com/manage/environments/[Environment ID]/uiflows/[Desktop Flow ID]/details
.
For more information, see Manage desktop flows.
The name
of the desktop flow connection (targeting a machine/machine group) to use to run your flow. The name can be retrieved from the URL of the same connection page in Power Automate. The URL format is:
https://make.powerautomate.com/manage/environments/[Environment ID]/connections?apiName=shared_uiflow&connectionName=[Connection Name]
.
Note
For more information, see Create desktop flow connections.
Tip
Alternatively, you can use a connection reference's logical name as the input of the connection instead of the connection name (usage example described below). The connection references are stored in the Dataverse table connectionreference and can be listed programmatically in the same way as desktop flows detailed in the List available desktop flows section.
For more information, see Use a connection reference in a solution and connectionreference table/entity reference.
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1
{
"runMode": "attended",
"runPriority": "normal",
"connectionName": "[Connection Name]",
"timeout": 7200,
"inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
POST https://[Organization URI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow HTTP/1.1
{
"runMode": "attended",
"runPriority": "normal",
"connectionName": "[Connection Reference Logical Name]",
"connectionType": 2,
"timeout": 7200,
"inputs": "{\"Input1\":\"Value\", \"Input2\":\"Value\"}"
}
{
"@odata.context": "https://[Organization URI]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.RunDesktopFlowResponse",
"flowsessionId": "d9687093-d0c0-ec11-983e-0022480b428a"
}
The inputs of the script are viewable in the run details page on the Power Automate portal (in Preview).
Warning
When using the API, there are some limitations to be aware of:
Triggering a desktop flow run with an account having "User" privileges will work. However, canceling the run and querying the status needs "Owner" privileges.
Dataverse impersonation isn't supported.
The input field content size is limited to 2 MB.
An optional parameter "callbackUrl" is available in the body of the RunDesktopFlow action. You can use it if you want to be notified of your script completion. A POST request will be sent to the provided URL when the script is complete.
User-Agent: EnterpriseConnectors/1.0
Content-type: application/json; charset=utf-8
x-ms-workflow-id: [Workflow ID]
x-ms-run-id: [Flow session ID]
POST [yourCallbackURL]
{
"statuscode": 4,
"statecode": 0,
"startedon": "2022-09-05T08:04:11Z",
"completedon": "2022-09-05T08:04:41Z",
"flowsessionid": "d9687093-d0c0-ec11-983e-0022480b428a"
}
If no callback URL parameter is provided, the flow session status should be polled from Dataverse (refers to Get the status of a desktop flow run).
Note
Requirements for the callback URL parameter
Tip
As the callback call isn't authenticated, some precautions should be taken
Similar to the Trigger functionality, you can also cancel a queued/running desktop flow. To cancel a desktop flow, use the CancelDesktopFlowRun action.
Authorization: Bearer eyJ0eXAiOi...
Accept: application/json
POST https://[Organization URI]/api/data/v9.2/flowsessions(d9687093-d0c0-ec11-983e-0022480b428a)/Microsoft.Dynamics.CRM.CancelDesktopFlowRun HTTP/1.1
HTTP/1.1 204 No Content
When an error occurs, the response has a different format that matches Dataverse error messages. The http error code and the message should provide enough information to understand the issue.
HTTP/1.1 403 Forbidden
{
"error": {
"code": "0x80040220",
"message": " Principal user (Id=526..., type=8) is missing prvReadworkflow privilege (Id=88...*)”
}
}
Events
Mar 31, 11 PM - Apr 2, 11 PM
The ultimate Microsoft Fabric, Power BI, SQL, and AI community-led event. March 31 to April 2, 2025.
Register today