Manage your Power Automate Desktop flows using Web APIs
Microsoft Power Automate makes it easy to build automations and provides a single, unified experience to manage, monitor and administer the Power Automate Flows. Power Automate portal (make.powerautomate.com) is the default way to manage Power Automate flows such as Cloud Flows and Desktop Flows.
With the introduction of Web APIs, you can manage desktop flows without the need of using UI – allowing administrators and Automation Center of Excellence teams to manage at scale.
In this post, we will walk through how you can use the Web API capabilities of Power Automate to manage the Power Automate Desktop flows.
Administering Power Automate flows
Before we dive into the Web APIs, here we will explain the existing capabilities that you can use via UI.
Initiate a cloud flow run
Ad hoc initiation of Cloud flows can be achieved by using the Run action on the top ribbon as shown below –
By navigating to the Monitor section of the Power Automate portal, cloud flow run activity, desktop flow runs, and desktop flow queue activity can be accessed.
Cloud flow run
Desktop flow run
For more details, refer: Monitor desktop flow runs
Desktop flow queue
For more details, refer: Monitor desktop flow queues
How to use the web APIs to manage your Desktop Flows
Until recently, you had to go to these setup pages and views to access key information like Desktop flow queues etc. To streamline and optimize the management of Power Automate Desktop flows, additional capabilities were added to the Power Automate Web API.
For more details, refer: Work with desktop flows using code
Below is the list of Desktop Flows related actions enabled by the Power Automate Web API
- List available desktop flows
- Get the schema for desktop flows
- Get the status of a desktop flow run
- Get desktop flow outputs
- Trigger a desktop flow run
- Cancel a desktop flow run
In order to explore these API actions, the first step is to gather details for setting up the authentication with Dataverse.
For more details, refer: Use OAuth authentication with Microsoft Dataverse
For this walkthrough we will use Postman and connect to the web APIs with OAuth authentication. To do so, you need to register the application in Azure AD tenant. Follow the instructions listed in the tutorial: Register an app with Azure Active Directory on how to create application registration for Dataverse.
For more details on using Postman, refer: Use Postman to perform operations with the Web API
To gather the Access Token in Postman, gather below information to populate into the Authorization section of the Request.
VARIABLE | INITIAL VALUE |
url | https://<your org name>.api.crm.dynamics.com (Example:https://orgXXXXXX.crm.dynamics.com) |
Clientid | 51f81489-12ee-xxxx-aaae-a2591f45987d (Application/Client ID from App Registration) |
Version | 9.2 |
webapiurl | {{url}}/api/data/v{{version}}/ |
Callback | https://localhost |
Authurl | https://login.microsoftonline.com/common/oauth2/authorize?resource={{url}} |
Examples of Desktop Flow management actions via Web APIs
1. List available desktop flows
Description: Get a list of desktop flows sorted by name
URL: https://[OrganizationURI]/api/data/v9.2/workflows?$filter=category+eq+6&$select=name,workflowid&$orderby=name
Operation: GET
Request:
Response:
2. Get the input schema for desktop flows
Description: For a given desktop flow (Workflow Id), retrieve the flow schema for inputs
URL: https://[OrganizationURI]/api/data/v9.2/workflows([WorkflowId])/inputs/$value
Operation: GET
Request:
Response:
NOTE: Input schema value is valid only if desktop flow has defined input variables.
3. Get the Output Schema for Desktop Flows
Description: For a given desktop flow (Workflow Id), retrieve the flow schema for outputs
URL: https://[OrganizationURI]/api/data/v9.2/workflows([WorkflowId])/outputs/$value
Operation: GET
Request:
Response:
NOTE: Output schema value is valid only if desktop flow has defined output variables.
4. Trigger a desktop flow run
In order to trigger a desktop flow run, ID of the desktop flow and name of the desktop flow connection (targeting a machine/machine group) are required.
ID of the desktop flow can be looked up using the List available desktop flows action and filter it by name.
Name of the desktop flow connection can be found in the URL of the connection.
Description: Trigger to run a given desktop flow (Workflow Id)
URL:https://[OrganizationURI]/api/data/v9.2/workflows([Workflow ID])/Microsoft.Dynamics.CRM.RunDesktopFlow
Operation: POST
Request:
NOTE: This action requires a to send request variables as JSON body as shown above.
Response:
NOTE: The response contains the flowsessionId that can be used to get the status of the desktop flow run.
5. Get the status of a desktop flow run
Description: Get the status of a desktop flow run for given flow session (FlowsessionID)
URL:https://[OrganizationURI]/api/data/v9.2/flowsessions([Flowsession ID])?$select=statuscode,statecode,startedon,completedon
Operation: GET
Request:
Response:
6. Get the desktop flow outputs
Description: Get the outputs of a desktop flow run for given flow session (FlowsessionID)
URL:https://[OrganizationURI]/api/data/v9.2/flowsessions([Flowsession ID])/outputs/$value
Operation: GET
Request:
Response:
NOTE: Output value is valid only if the desktop flow has produced any outputs, else the response will be empty.
7. Cancel a desktop flow run
Description: Cancel a desktop flow run for given flow session (FlowsessionID)
URL:https://[OrganizationURI]/api/data/v9.2/flowsessions(d9687093-d0c0-ec11-983e-0022480b428a)/Microsoft.Dynamics.CRM.CancelDesktopFlowRun
Operation: GET
Request:
Response:
When you have the flow in running state, Response will be as below:
HTTP/1.1 204 No Content
In case if the flow is not in running state, below response message is shown –
We hope this post helped in providing information to manage Power Automate desktop flows from an external context.
Postman Collection for the above actions is available here.
Happy Automating!!!