Azure Logic Apps Custom Connectors

Introduction

Azure Logic Apps contains a vast library of first-party Microsoft connectors and 3^rd party connectors for popular SaaS, PaaS and on-premises systems. Even though the current library boasts more than 220 connectors, it is impossible to have complete coverage for every possible system that is used within the enterprise. The good news is custom connectors can fill gaps in the ever-growing library of connectors. In this article, we are going to walk through creating and deploying a custom connector for Azure Logic Apps.

What is a Custom Connector?

A custom connector, in Azure Logic Apps, is an abstraction that sits on top of a REST or SOAP API and has an Open API (formerly known as Swagger) contract that allows developers to easily ‘plug-in’ their connector to Azure Logic Apps. By using Open API, developers can take advantage of dynamic content that allows for the ability to populate input attributes/parameters but also use outbound attributes in downstream actions.

Custom connectors fulfill gaps that may exist within the existing connectors offering. It isn’t practical to have a connector for every service on the planet. But, by having a custom connector framework, it allows customers to address those gaps in an efficient way to address specific business needs.

Image source: https://docs.microsoft.com/en-us/connectors/custom-connectors/

PowerApps, Microsoft Flow and Azure Logic Apps

As you may have noticed from the previous image, custom connectors are available for PowerApps, Microsoft Flow and Azure Logic Apps. For Azure Logic Apps, custom connectors get registered within Azure by creating a resource within the Azure Portal or through an ARM automation script. While Azure Logic Apps custom connectors share the same behavior as PowerApps/Microsoft Flow custom connectors, the deployment model is different as PowerApps and Microsoft Flow use Business Application Platform environments which act as a perimeter boundary for those services. While you can use the same definitions when creating custom connectors with these services, you can’t deploy it once and have all three technologies use it.

Publishing your Connector as a 3^rd Party Connector

A frequent query that ISVs will ask is what is the difference between publishing a custom connector and publishing a connector that is available for all customers? An ISV can create an API, document their API using Open API and then provide the Open API files with some instructions as to how a customer can create a custom connector. While this approach does work, it creates some friction for customers. It also makes dealing with updates problematic as you are trying to keep your client code in-sync. Alternatively, and if you own the underlying API/service, you can publish your custom connector as a 3^rd party connector by working with the connector team at Microsoft. Note, there is an on-boarding process where your connector will be validated by their team and you will also be subject to a specific SLA and terms and conditions.

Security

Security is naturally an important topic when connecting systems. One of the benefits of creating a custom connector is having a reusable foundation so that you do not need to continue to solve the authentication method over and over again. The good news for developers is that Azure Logic Apps have deep authentication support, including 4 different security schemes:

• API Key
• Basic Auth
• None
• OAuth2

To streamline the ability to connect to Oauth 2 Identity Providers, a generous list of providers is provided including Azure Active Directory.

Creating a Custom Connector

A common misconception about custom connectors is that you need to write code in order to build one. This isn’t necessarily the case. What is important for Azure Logic Apps is that the underlying service is decorated with an Open API spec. The reason for this is Logic Apps needs to understand all of the inputs and outputs to draw the appropriate trigger/action cards within the designer. This approach also allows you to perform simple mapping as you transition data from one card to another card.

A term that is often used to define the type of custom connectors where the code has not been written is a ‘codeless’ custom connector. In this scenario, a developer is really defining the Open API spec that lines-up with the underlying API service, which you may not even own. In some situations, you may not want to expose all of the underlying operations and can use your custom connector to abstract those services by not exposing them to Logic Apps.

There certainly are situations where you do need to write some code. For example, if you have legacy applications that reside on-premises you may choose to write an App Service API App and expose your Open API spec by using swashbuckle in your project. Alternatively, you may want to perform some calculations that would not be practical to do in Logic Apps. Instead, you may choose to write an Azure Function. Using an Azure Function back end, in a consumption plan, may be an inexpensive way to host that functionality.

Scenario

For this blog post, we are going to use a codeless approach. As a big sports fan, I am interested in pulling in sports-related data into my logic app. This may include schedules, standings, statistics, and odds. I performed a brief web search and found a site called Fantasy Data which exposes this data using restful APIs. As a bonus, they have also provided Open API spec files for their APIs which simplifies the task of integrating this with Azure Logic Apps. You can sign up for a Sports data free trial here and then download the Open API spec files.

To create and use a custom connector within Azure Logic Apps, perform the following steps:

1. 1. In the Azure Portal, navigate to the Marketplace and search for Logic Apps. Locate Logic Apps Custom Connector and click on it.
   2. Provide a Name, Subscription, Resource Group and Location for your custom connector

1. You will see the shell of your custom connector has been provisioned. We now need to configure it by clicking on the Edit
2. The custom connector wizard will now appear. This is a similar experience that you will see from the PowerApps and Microsoft Flow maker portals. We now have a couple of decisions that we need to make including the type of API endpoint we want to wrap and the import mode. For the purposes of this blog post, we will choose REST and OpenAPI file since Fantasy Data has provided us with a download of our Open API spec files.
3. As you can see Fantasy Data includes a lot of different data feeds for sports. In our case, we are going to focus on college football odds with bowl season right around the corner.
4. We now have the opportunity to provide our own creative touches by uploading a connector icon and adding a description. By default, when we consume the Open API files, our security Scheme will be set, as will our Host and Base URL.
5. The next tab we need to address is Security. Once again this is information that will be included in our Open API spec file. In our case, the Fantasy Data API depends upon an API Key to authenticate. When you create an account on their site, they provide you with two API keys. They use this key to authenticate you, but also to track your usage. Since all of these parameters are there in our Open API spec file, we do not need to make any changes to our Parameter label, Parameter name or Parameter location. Under the hood, Logic Apps will use this information to assemble a header that will be passed to the Fantasy Data API in a manner that it expects.
6. In the Definition tab, we have the ability to override any actions that appear in our API. For example, we can exclude them and change their visibility, which controls how parameters are displayed in the connector card within the designer. Once we have finished configuring these settings, we can click on the Update connector link which will validate and publish our connector.

Using our Custom Connector in Azure Logic Apps

For our particular scenario, we will build our own service around this Fantasy Data API so it is easy to consume by our own systems. To enable this scenario, we will perform the following steps:

1. We will add an HTTP trigger to our logic app, but we will change the method to a GET and provide a Relative path that allows us to specify a year and a week in order to get the information for football games occurring for a specific year and week.
2. We are now ready to add our custom connector to our logic app and can do so by starting to type the name of it in the Choose an action Once found, we will see all of the related actions available to us. In our scenario, we are looking the Pre-Game Odds by Week so we will choose that operation.
3. Since we haven’t used this connector in Logic Apps yet, we will get prompted to create a connection. Here, we need to provide a Connection Name and an API Key. If you recall, this is the same API Key that we discussed when publishing our custom connector as it is part of the underlying API security scheme.
4. With our connection established, we now need to configure our action. For format, we want the output to be JSON. For both the season and week parameters, we can use dynamic content from our HTTP trigger where we defined path parameters for both of these values.
5. To complete our flow, we will add a Response action which will return our results to our caller.

Testing

To test our logic app we will use Postman to construct our HTTP request that we will send to Logic Apps. What we are going to look for is the upcoming odds for the Arizona State Sun Devils (my alma mater) vs Fresno State Bulldogs.

As you recall, as part of our trigger we defined path parameters that included the year and the week. Since bowl games are technically post-season we will provide 2018POST for the year and 1 for the week as they play in the first week of bowl season.

When we look at the results, we can find our game and it looks like Fresno is the favorite team. Not encouraging, but I have confidence in ASU to pull off this win.

Other Considerations

Sharing

When it comes to sharing custom connectors in Azure Logic Apps, the Azure documentation indicates: “Custom connectors in Logic Apps are visible and available to the connector’s author and users who have the same Azure Active Directory tenant and Azure subscription for logic apps in the region where those apps are deployed.”

In this example, the custom connector was published to a resource group called Turbo360Blog. But it is still accessible to logic apps that exist in other resource groups. What you do need to be aware of is that the region really becomes a delimiter in this scenario. The custom connector will not be visible to a resource in another region.

But, this behavior does bring up an important situation. In the event you are writing a ‘codeful’ connector, you are likely going to have different versions of that connector based upon your development lifecycle and the environment i.e. Dev/Test/Prod. You need to ensure you are able to identify this ambiguity to avoid unwanted behaviors.

On-premises Data gateway

Another important scenario is building custom connectors that can connect to on-premises assets. This is a supported scenario. During the creation of the custom connector, there is a checkbox that allows you to send traffic to your data center using the on-premises data gateway.

Conclusion

In this blog post, we discussed custom connectors and their role within PowerApps, Microsoft Flow and Azure Logic Apps. Custom connectors are really important as they unblock projects that can’t proceed due to a lack of connectivity.

Creating a custom connector is not as daunting as it may look and is simple when you compare to other platforms. So embrace the opportunity to create reusable connectors that can be leveraged across your enterprise!