Insights

Power Automate: Custom Connectors

18 May 2021, Alexandra Pepperell

Microsoft, Power Platform

Power Automate is an incredibly powerful tool that allows us to work smarter instead of harder – but what happens when there isn’t a connector for that system? This year I delved into creating Custom Connectors for Power Automate using several different API interfaces. True to their brand, Microsoft has provided a wonderful interface to approach custom connectors either as low code or all code using Swagger. Using the two hand in hand provided a quick creation option with full functionality.

General 

This is the quickest step creating the connector and giving your connector a name. We can come back to this step later and you can add a custom icon for the system you are connecting to. Creating a custom icon may seem like a ‘pretty’ functionality, but it does make it easier to identify the connector and its parameters later when you are swathing through long automations with longer lists of parameters. 

Enter the Host. This should be at the start of the API documentation, and if necessary, the base URL (perhaps a versioning on the system side, such as /api3. If in doubt, leave this as a single slash (/). 

Security 

If you are not familiar with API security, here is a summary of two common ones that I have encountered. 

Oauth 2.0 (https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/) 

Oauth 2 offers multiple options for users to connect either directly using their own credentials or utilising a service account. These connections use an authorised token passed back and forth for each request. The token is defined at the start of the connection from user credentials and refreshed at defined intervals. You could also use a service account.  

On the first connection, the provider will provide a login page for the user, and on successful login show an authorisation page, to confirm the scope of the application and request approval to continue. 

Note that the redirect URL is the same for both. You will need to provide this when you setup the API interface on the provider’s site.  

No matter how many times you enter the Client id, Client secret and Refresh URL, it will always clear when you’re looking at the saved connector. Just remember to re-enter it, if you need to edit the Security details of the connector.  

API Key (https://swagger.io/docs/specification/2-0/authentication/api-keys/) 

If the connector is in service as a system account (for instance to provide bulk data transfer between systems) and specific user settings are not required, an API key could also be used. Please consider carefully which is suitable for your application and review the providers’ API documentation for what is available.  

API keys can be passed through on the Header or Query, refer to the API documentation requirements. Take note of any examples provided in the documentation – what is the API Key’s parameter name? For one of my connectors it was ‘hapikey’, if spelt incorrectly, the request would fail. 

Definition 

When you first start on the definitions, you’ll find that well defined API documentation will save you a lot of time. My first couple of experiences with API documentation left me dazed and confused. The defined request requirements and response bodies did not work. It took a few tweaks to realise the documentation was wrong, perhaps a mistype or misunderstanding between documenter and developer or perhaps even a versioning change. Then I came across a perfectly written API documentation that seamlessly transitioned across and was immediately easy to use, it was completed before my coffee was!  

In the Definition of the connector, is where you will define the Actions and Triggers you want the connector to perform. There is no need to add all actions that are available in the API. Only add the items you require at this stage; you can always edit and update the connector when more actions/triggers are required.  

Actions/Triggers Request  

Actions are operations that you want the Connector to perform including GET, POST, DELETE, POST, HEAD, OPTIONS, PATCH. I was using the GET and POST requests, but this will depend on what your providers API supports. 

Note that some API’s have specific URL’s for requests, you’ll find this in the documentation. If you are using an API Key that includes it in the header, you do not need to specify this in the Headers section again – the Security section of the Connector will append the API key when required.  

Check for any variables in the Path. These need to be entered in curly brackets { } to define a variable in the path.  

Query parameters should also be entered in the URL after a Question mark, for example, in /items?id=####, the query parameter is id. 

The Body of the request is how the request will be formatted for the API to receive. After saving, you can edit each of the body parameters, by clicking on the ellipse and then Edit. 

Editing Parameters 

Each Parameter can be edited or deleted after creation. You can only create these using the ‘Import from Sample’ button. Some notes: 

  • Description can be copied from the API documentation; the description provides more detail to the user about the purpose of the field when the connector is being used in Power Automate. 
  • Default Value can be set and must be set if the field is required, and visibility is set to None. 
  • Is required? Yes/No. Remember to set this for any required parameters. Refer to API documentation to confirm. 
  • Visibility defines the level at which the user will be shown this field. If you expect the user to always see it, I recommend using the important option. Other options require the user to click for ‘advance settings’ or ‘see more’ to find and enter the field. 
  • Type allows you to define the type of content of the field and sometimes the format. 
  • Dropdown type provides some content control for static options. 

 

 

Action/Trigger Response 

 

Like Request, Response requires a body (optional Header), using the Import from Sample provides a great starting point to add the parameters, however I recommend clicking into the Default response to edit the parameters.  

This is particularly relevant if your response has objects, as there may be multiple response parameters with the same name. Editing these to ‘friendly names’ now, will save confusion down the track! This can be difficult to see using the UI, so I recommend switching over to the Swagger interface to review and rename the response parameters. 

Notice in this example (Swagger) of a response object, the names of the fields are generic. Without the identifying titles I’ve added the object name to help identify the value. These can be with or without spaces and do not need to be enclosed in quotes.  

Test 

Connections 

Before you can test your connector, you need to ensure you can connect to the API. Where possible, it is a great idea to name your connections (especially if there are Dev and Production environments within the connecting system), often this isn’t available. 

On the first connection, you’ll often need to login to the API’s system using authorised credentials and approve access permissions. If necessary, have an authorised representative on a Teams call, ready to enter their credentials and approve the requested permissions. Once approved, the representative can sign out on your machine, but the connector will retain the approved credentials.  

Operations 

Once a connection has been established you can test your actions without building out complicated flows. This view provides both the Request and the Response and is a great way to troubleshoot connectors initially.  

When you are ready, click the Update Connector button at the top and you are ready to start accessing your Custom Connector through Power Automate. 

Final Notes 

  • Remember to check your parameter types against the documentation, sometimes sample data is not enough for the UI to ascertain the correct data type.  
  • If you cannot find or edit the parameter in the UI, switch to Swagger and step through the code. A good example of this is the input type File which is not available through the UI, instead only available through form-data. Note that all parameters must be updated to in: formData and consumes, must also be updated. 
  • Permissions – If you needed an authorised representative to approve the connectors initial connection, they’ll be required each time you move between environments. 
  • If you are using a custom connector in a solution, you will need to move the custom connector in its own solution and import ahead of the main solution. This ensures the system knows how to use the connector before it imports the solution that makes use of it. 
  • After you have started using your connector in Power Automate, changes you make to the connector don’t always immediately appear in your Flows. To force the update, try uploading a different connect icon (Under 1. General), then click Update connector (top right). You can always change it back later. 
  • When all else fails, go to Postman.com and create the initial API connection there, then step it over to Swagger. There is no longer a direct import option available (Postman only exports 2.0 and up, Power Automate only accepts Postman 1.0. Hopefully there will be an update on this front in the future!). This is a great way to determine if it’s the UI, connection setup or the documentation causing the issue before you get too frustrated. 

Try it out – see how you can quickly integrate your systems using the Power Automate Custom Connectors. If you need some ideas on how Automation and the Power Platform can benefit your business, get in touch with us at MOQdigital, we are ready to assist you.