Custom Connectors for Power Automate: GUI vs. Code

When we are developing our apps and flows, sometimes we need to access 3rd party services that provide useful information or resources: currency exchange rates, text translation or document conversion are some examples of these. If we want to use them within a flow, we normally need to use the HTTP connector, specifying the request method, headers, parameters and authentication method.

However, many citizen developers may not be comfortable working with the HTTP connector and configuring it in the right way. This is why we may want to create our own custom connector to connect with APIs, to make use of those 3rd party services easier for makers. The custom connector only needs to be defined once – then any maker can select it in Power Automate flow editor and use it like a built-in connector.

In this blog post I will guide you through some ways to create your own custom connector:

• Method 1: Create from blank – You prefer to use graphical interfaces (GUI) and wizards instead of text based developer tools.
• Method 2: Create from an OpenAPI v2 (Swagger) definition file – You’re a professional developer and like to use code editors.

So, regardless of whether you prefer to avoid writing code or feel comfortable using professional development tools, this blog post has got you covered.

Use case: TV Maze API

TV Maze API is a free REST API that has multiple endpoints to get information about TV shows and movies. Among different methods, you can search for shows or movies, get seasons, episodes, cast and even the schedule. If we were going to use the HTTP connector to get shows or movies based on a keyword search (Batman, in this case), we would do the following:

After that, we would need to parse the response in JSON format, and then access different fields as needed: score, title, type, language, genres, etc. A workflow that searches for movies and TV shows and builds an HTML table with the results would be like the following:

As you can see, there are many steps involved in the process. You might need to understand some advanced concepts, like calling an HTTP URI or parsing JSON results returned by the API. Therefore, let’s try to create our own custom connector to make things easier.

Method 1: Create from blank (GUI)

Let’s start with creating a custom connector using the graphical UI. In the “Custom connectors” element under the “Data” section you will find the different options to create it. We will select “Create from blank”.

In order to create the custom connector, we will have to go through a few steps in the connector wizard.

Step 1 – General information

First of all, we will have to name our new custom connector, define its icon, description, scheme (normally HTTPS) and host (base URL of the API).

Step 2 – Security

To access the API we may need to use some security mechanism:

• No authentication.
• Basic authentication: We need to provide a user and a password to access the API when using basic authentication.
• API Key: We need to provide an API key to access the API.
• OAuth 2.0: If the API uses OAuth 2.0 authentication, we need to configure some parameters like identity provider, authorization URL, etc.

For our scenario, we can use the TV Maze API with no authentication.

Step 3 – Definition

This is the place to define what actions and triggers our custom connector will have. If we want to create a new action, we will need to provide the following parameters:

• Summary: Short description of the action.
• Description: Long description of the action.
• Operation ID: A unique string identifier for the operation.
• Visibility: Do we want this action to be visible in the first position when we see the list of actions of the connector? Or do we want to hide it? That’s what visibility configuration is about.
• Request: What API method do we need to call when using the action, and what parameters does it need? When clicking “Import from sample” you can specify information required to configure the request:

• Response: What fields does the API method return? As we did for the request, we are going to define the response based on a sample payload (result of the call to https://api.tvmaze.com/search/shows?q=Batman):

As you can see, all fields returned by the API method call are automatically identified once we select “Import”:

There’s a validation section at the end of the page that shows if everything is correct. At this moment we can also can save the connector definition, by clicking on “Create connector” button.

Step 4 – Code (Preview)

In this section we can add C# code to transform request and response payloads programmatically, although the operation must have 5 seconds maximum execution time, and can’t be more than 1MB. You can find more information about this feature at Learn.

In this case, we can leave this option disabled, as we don’t need to execute custom code in any of the operations.

Step 5 – Test

Finally we can test connector operations from this screen, specifying a connection and parameters if needed.

We can check that the operation is executed successfully (status code is 200). In this example we got some validation errors: our connector expected an average rating value as a number, and it returned a string. It probably means that we have to change the data type of this field in the response definition of the search operation, as field data types are inferred from the response sample we entered before. Unfortunately OpenAPI v2 doesn’t support null values, but v3 does (remember that we have to use v2!).

After that final step, our connector has its first operation: Search for TV Shows and movies. If we wanted to add more operations, we would simply repeat these same steps to define all of them.

Method 2: Create from an OpenAPI v2 definition file (code)

If we are used to use professional development tools, we can create our custom connector programmatically. We should have the following tools installed:

1. Power Platform CLI (a.k.a. “PAC CLI”), a command line tool to perform different operations related to environment, solutions or connectors.
2. Install Power Platform Tools extension for Visual Studio Code to access environments and solutions from within the code editor.
3. (optional) Install the OpenAPI (Swagger) Editor extension for Visual Studio Code to create and edit OpenAPI definition files.

To create the basic definition for a custom connector, we run the following command from any terminal window or from within Visual Studio Code terminal.

pac connector init --connection-template "NoAuth" --generate-script-file --generate-settings-file --outputDirectory "TV-Maze-Pro-Dev"

This is going to create 3 different files in the “TV-Maze-Pro-Dev” folder:

• apiProperties.json: It contains information such as the brand color, connection parameters or authentication information. These properties are not part of the API definition.
• script.csx: C# code to execute in order to transform request and response payloads programmatically.
• settings.json: File to store location of custom connector files: API definition and properties, custom code, and icon.

Additionally, we need to add a new file called apiDefinition.swagger.json, which will include the API definition. You can read about all its options and coding standards here, but if you don’t want to write its content from scratch, there’s a useful template in the Power Platform Connectors Github repository. Besides that, in the same repository you can find the definition files for a bunch of existing connectors, which is an excellent resource to learn on how to build a new one.

Obviously, writing an API definition file from scratch is not an easy job, and I recommend using some kind of generator tool like Swagger Inspector: It creates the definition file based on JSON content (mock file or response from an API call). Additionally, you can also use OpenAPI (Swagger) Editor extension in Visual Studio Code to add or edit the swagger definition file. In any case, you can read the official documentation for the OpenAPI v2.0 specification here.

When you’re finished with the definition file, it’s time to add the custom connector to the one of the Power Platform environments. We perform this step using the Power Platform CLI:

pac connector create --api-definition-file .\apiDefinition.swagger.json --api-properties-file .\apiProperties.json --icon-File tv-maze-icon.png --environment 8615fce8-2665-e89f-abfb-69712207f987

If everything is well defined, the custom connector should be ready to be used from within any Power Automate flow or Power Apps app in the selected environment.

If we want to know the connectors that are currently deployed to an environment, you can run the following command:

pac connector list --environment "8615fce8-2665-e89f-abfb-69712207f987"

And of course, if we need to update the connector definition, we would run the following command (we also need connector id value, that is shown in the previous command results):

pac connector update --api-definition-file .\apiDefinition.swagger.json --connector-id a06c08da-3214-ee11-8f6d-000d3a248999 --environment "8615fce8-2665-e89f-abfb-69712207f987"

To further improve the process, you could manage connector source code with ALM tools like GitHub or Azure DevOps.

Finally, you can find the sample connector source code used in this blog post from our GitHub Community repo.

Summary

Using 3rd party software services from Power Automate or Power Apps could be a difficult task for a maker without any programming background. Thanks to custom connectors we can make the use of these APIs easier, leveraging all the features of the Power Platform to create powerful applications and workflows.

By the way, do you know what happens when someone that created a custom connector leaves an organization? Check out this article written by Timo Pertilä to find out!