Power Platform Pro | Custom Connectors - Part 1

The following is a condensed intro to Custom Connectors and various Integration Options using Power Platform and Microsoft Azure Services.

When creating #PowerPlatorm solutions, the core of the value most often lies in the connections to multiple backend systems to fetch, combine and update data. Whether a simple Power App to report back time, or a complex Power Automate Flow that spans multiple data sinks, the better the integration of the Low Code solution, the better the outcome and the more benefit it provides.

The Microsoft Power Platform comes with a plethora of ready-to-use connectors to hundreds of systems by a diverse set of providers. But sometimes there just isn't the right connector available, for an inhouse developed system or maybe the solution needs to move from point-to-point integrations to an enterprise integration layer.

This is where Custom Connectors come into play. A custom connector is essentially an OpenAPI specification (SWAGGER file) imported into Power Platform. The definition of the connector can be as complex or simple as the specification allows. The easiest way to start with custom connectors is to use the popular tool Postman to create a collection of HTTP(S) requests as per the desired APIs specification and then just import the collection into Power Platform

In this demonstration, the goal of the custom connector will be to fetch the current weather from an external API. To make this sample realistic, the external weather API expects a Latitude and Longitude parameter - something we would like to hide from the Low Code users of the connector. Instead Makers in Power Platform should be able to call the service with an address, that is geocoded and then forwarded to the API.

Before diving into the details of hiding this complexity, let's define the required HTTPS requests in Postman. For this sample, we will use two APIs. Bing Maps to geocode an address and OpenWeather to fetch conditions for a given lat/lon.

To use BING to geocode an address, first get developer keys for the API in the BING maps portal -> https://www.bingmapsportal.com

Same goes for the OpenWeather API, sign up and get keys from openweathermap.org -> API Keys -> "Generate"

Head back to POSTMAN. Create a new collection and add a new request to the BING MAPS API. Here is the required HTTP call to create. Note the placeholders in curly brackets {{}}. These are references to POSTMAN collection variables that can be used to hold the values.

GET /REST/v1/Locations?q={{address}}&key={{key}
Host: dev.virtualearth.net        

Here is the important part of the response. We will use the coordinates extracted from the "geocodePoints" array, to feed it into the request for the OpenWeather API.

"resourceSets":?
????????{
...
"confidence":?"Medium",
  "entityType":?"Address",
    "geocodePoints":?[
      {
        "type":?"Point",
        "coordinates":?[
          48.3836358,
          16.1979656
          ],...        

Let's create a new request for the OpenWeather API, in the same POSTMAN collection. Again LAT and LON are stored in collection variables, as is the API Key.

GET /data/2.5/weather?lat={{LAT}}&lon={{LON}}&appid={{APIKey}}
Host: api.openweathermap.org        

And here is a snippet from the response output:

..
"weather":?
????????{
????????????"id":?800,
????????????"main":?"Clear",
????????????"description":?"clear?sky",
????????????"icon":?"01d"
????????}
????],
????"base":?"stations",
????"main":?{
????????"temp":?284.49,
????????"feels_like":?282.88,
????????"temp_min":?282.79,
????????"temp_max":?285.96,
????????"pressure":?1020,
????????"humidity":?46
????}...        

At this point we can already save the collection and export it to a JSON file, to be used by our Power Platform custom connector (Export can be done in v1.0 or v2.1)

Heading over to the Power Platform Maker Portal (make.powerapps.com), go to Custom Connectors > +New custom connector > Import a POSTMAN collection.

A 5-step wizard guides through the creation of the custom connector from the specification. In this simple example we can skip to Section 3. Definition, as we combined 2 different APIs, we cannot specify a common Authentication schema for both. The section 2. Security would provide respective options to put an API key in a specified header or query parameter. But again, as our 2 APIs expect the APIKey in different query parameters, we need to specify them in the specific operations themselves, leaving security to No Authentication and heading to 3. Definition directly.

You can see that the wizard displays all the details of every operations as well as the extracted parameters from the query URLs. Each operation is split into a general section, a Request section and a Response section. Let's take a look at the BING Maps geocode operation. In the Request section, select the key parameter to configure it and specify a default value.

This will bring up a detail dialogue to set display options for the selected parameter. The fields name and description can be used to change how the parameter is displayed in Power Apps and Power Automate designers. As this is the key parameter we set the Visibility to internal and set a Default value with our API Key. In part 2 of this article series we will see how to create much more complex and dynamic parameters using this exact dialogue. For now return to the operation and do the same for the OpenWeather API - selected the appid parameter and set it internal as well as set a default value.

The minimum baseline to create the connector is set. Lets hit "Create connector" and it should take a minute to generate. As soon as its generated, Section 5. Test can be used to create a connection using the new connector and test the operations.

The responses from the operations are still only key-value pairs. To nicely display the returned values to Makers in the designer, it is necessary to describe the response schema for each operation. The easiest way to do this, is copying the response from POSTMAN and navigating to the operation in the Power Platform designer. In the Response section, select the "default" response and select +Import from sample. Paste the whole response and the designer should infer a schema and generate parameters for the app and flow designers. Again all parameters are editable like the input parameters for the Request.

With this, Update the connector and create a new Flow that uses this connector. Observe how the designer picks up any edits and displays input and output parameters as specified in the Custom Connector designer.

This initial article of the series, was a quick intro into the most important concepts of custom connectors. There is much more to it and a lot of good practices that have been omitted for brevity. In the follow up article we will see how to combine the 2 APIs into a single Custom Connector operations and also add security and format transformations using Azure API Management.