Build your next OutSystems app Microsoft Power Automate enabled
Microsoft Power Automate
Power Automate’s ease of use truly allows any user to automate repetitive tasks. The creation of a Power Automate flow starts with the selection of a trigger. There are three types of triggers: manual, automatic and scheduled. The trigger determines when subsequent activities in the flow — actions — are run — manually initiated by a user, automatically after an event occurred or periodically based on a schedule.
Triggers and actions are available in Power Automate via Data Connectors. Microsoft itself provides numerous Data Connectors for the Microsoft 365 and Azure ecosystem. These are supplemented by additional Data Connectors from third-party providers for connecting other (cloud) services. Finally, Power Automate customers can also create their own custom Data Connectors and make them available to their users.
Data Connectors are described by an OpenAPI Version 2 definition file (with some additional extension attributes). That definition can either be created using the visual assistant in Power Automate or by any other editor and then imported. Here are some links for more information about OpenAPI Version 2 aka Swagger.
- Basic Structure (swagger.io)
- OpenAPI Specification — Version 2.0 | Swagger
- Swagger Editor
- Custom connector OpenAPI extensions
Custom Data Connectors are a premium feature of the Power Platform and require additional licensing.
The primary target group of Power Automate is the office worker, who automates his own workflows in self-service. Azure Logic Apps, on which Power Automate is built, offers even further functionalities. Logic Apps is aimed at IT professionals and software developers building complex automations between applications and services for their organization.
An action in a Power Automate flow is a request to a REST API. So, for every action we want to have in our Power Automate Flow we have to expose an endpoint in OutSystems.
A trigger in Power Automate can either be a webhook trigger or a custom polling trigger. The latter periodically checks an API endpoint if new data is available and triggers the flow. Webhook triggers wait until our OutSystems application pushes data and then runs the flow. That is what we are using in this walkthrough. If you want to know more about custom polling triggers, see Use a polling trigger for Microsoft Power Automate | Microsoft Docs.
Whenever a webhook trigger is used, Power Automate generates a unique webhook URL. In addition, Power Automate performs a registration request to a — in the Custom Connector definition file — defined API endpoint. That request includes the generated webhook URL along with any additional data our OutSystems application needs to “know” for sending notifications. The triggering user may be asked to enter that additional data, or it is predefined and hiddenly sent.
We therefore need another API endpoint in our OutSystems application to handle webhook registrations.
Demo Application — Overview
To show how to integrate Power Automate with an OutSystems application i have prepared a demo application available on the forge: Power Automate Integration Demo.
It is a “most basic” expense tracking application. You can enter an expense with a title, a category, and an amount. Thats it.
Power Automate users should be able to trigger a flow whenever
- any expense entry is created
As actions we want to offer a Power Automate user the following
- Retrieve details of an expense entry for a given id
- Retrieve all expense entries of a given category
- Create a new expense entry
The Power Automate Integration Demo has a dependency on the CloudEvents component. CloudEvents is a webhook notification service i developed based on the cloudevents.io specification. You can read more about the service on our dedicated forge component microsite ANVIL.
CloudEvents handles webhook registration for one or more event types (and optional subject/topic) and pushing events to registered webhooks.
To follow along go ahead and download the application from the forge into your environment. A personal environment is sufficient.
Now it is time to take a closer look at the two important building blocks of the application.
Demo Application — Exposed REST APIs
The PowerAutomateExpensesAPI module exposes REST API endpoints. Note that Authentication is set to Basic Authentication. The implementation in the OnAuthentication handler contains the default implementation using User_Login from the System module.
Power Automate Custom connectors support the following authentication methods
- Basic — Username and Password authentication as shown in the demo application
- API Key — any key in the header or url of a request
- OAuth — a central identity service (Azure AD, Okta etc.) supporting the OAuth authentication flow. (my recommendation in public facing environments).
Besides the resource-based endpoints (Categories and Expense Entries) there is also a CallbackRegister and CallbackDelete endpoint. The first accepts a POST request to /Callback and the latter a DELETE request to /Callback. Those two are responsible for registering and deleting a new Power Automate trigger.
The CallbackRegister performs the following
- Query a static entity if the registration event type matches an entry and throw a 400 Bad Request if not
- Register the webhook target url with the CloudEvents Notification service and throw a 429 Conflict if not successful
- Return a 201 Created Status
The CallbackDelete deletes the registered webhook target url from the CloudEvents Notification server.
Calling the DELETE callback endpoint is automatically performed by Microsoft Power Automate whenever the trigger or the complete flow is deleted.
All other resource-based endpoints wrap the corresponding server action to return results.
Demo Application — Notifying registered webhook subscribers
Emitting an event to our webhook subscribers is done in the AddExpense server action:
- Create the expense entry
- Builds and serializes the event payload (in our case that is just the Expense Identifier)
- Calls the CloudEvents_EventPush service action with the serialized payload and the Expense.Created event type.
Custom Connector — Definition
I already prepared a custom connector definition. You can find the completed definition file in this github repository
Download the apiDefinition.swagger.json file to a local folder. Then open Power Automate.
In the Data menu click on Custom connectors and then in the top menu on New custom connector — Import an OpenAPI file. Select the downloaded swagger file and click on Continue.
Change the Host to your OutSystems environment.
Then click on Save Connector.
Let us look at some key elements of the definition file
Locate the Callback path and the x-ms-notification-content property. Below the event payload is defined. That means that this data is sent when your OutSystems app is triggering the flow.
The x-ms-trigger property under the post path tells Power Automate that this is a trigger definition and the x-ms-notification-url under the TargetUrl property tells Power Automate to place the unique webhook url into this parameter property.
To build your own definition file you can either use the visual editor of Power Automate or any other code editor. A good course on how to build a custom connector for Power Automate can be found here.
If everything is correct your Connector is now ready and can be used in flows. Add the trigger to a new flow and provide your OutSystems login credentials for the Basic Authentication.
Place any other action below the trigger to react to incoming webhooks from your OutSystems application. Test your flow (Manual).
Open the Demo application and create an expense entry. Your Power Automate Flow should trigger shortly after saving the entry.
I hope you liked it working through as i had fun creating it.
If you have difficulties in getting up and running, please use the OutSystems Forum to get help. Suggestions on how to improve this article are very welcome. Send me a message via my OutSystems Profile or respond directly here on medium. Happy low coding!