Office 365

Creation of Custom Connector for Power Automate – BugHerd API connector

Sierpień 6, 2020 0
Podziel się:

During one of the recent projects, we were asked to do an integration with BugHerd using Power Automate. BugHerd is a simple website that allows collecting feedback and track bug. We essentially needed to synchronize tasks between BugHerd and another bug tracking system – Trello.

The requirements were the following:

  • Whenever there’s a change to a task in BugHerd, reflect those changes in a corresponding task in Trello
  • Perform some periodic cleanup tasks on BugHerd tasks and comments

So, translating to Power Automate, we needed a trigger and some actions for both BugHerd and Trello. With Trello, there is no problem, there is an official connector in Power Automate which does everything we needed. However, BugHerd does not have an official Power Automate connector. Luckily, BugHerd has its own API and support for webhooks, so they could be used to communicate with BugHerd. And since Power Automate lets you create your own custom connectors, we decided to create one, so we could utilize it in the future (instead of having to use HTTP action).

Microsoft provides multiple ways of creating custom connectors for Power Automate (https://docs.microsoft.com/en-us/powerapps/maker/canvas-apps/register-custom-api):

  • Create from an OpenAPI definition
  • Create from a Postman
  • Create from scratch

Unfortunately, since all common BugHerd openapi auto discovery throws 401 Unauthorized exception we had to start the creation from scratch. BugHerd’s API is well documented here. Using curl we were able to create a collection of endpoints and their responses and put them into swagger definition file using Swagger Editor site.

Figure 1:BugHerd API in Swagger Editor

Figure 1: BugHerd API in Swagger Editor

Having an OpenAPI/Swagger definition, we could start registration of a new custom connector in Power Automate. We started by, going to https://flow.microsoft.com and once logged in, went to Data -> Custom Connectors using the left navigation.

o365 2 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 2: Navigation to Custom Connectors on Power Automate site

Once there, click on Custom Connectors page, clicked New custom connector and selected Import from OpenApi file.

o365 3 - Creation of Custom Connector for Power Automate – BugHerd API connector

This started a wizard that guided us through the whole registration process.

First, we needed to apply some general information about the connector:

o365 4 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 3: Custom connector wizard in Power Automate – General

In the Security tab, we specified authentication. BugHerd API uses basic authentication with a username and a password. Since those are the default settings in the wizard for basic authentication, we left those settings intact.

o365 5 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 4: Custom connector wizard in Power Automate – Security

Definition tab is where all the fun happens. Here you may specify Actions and Triggers that will later be available for the custom connector. If you import your own OpenAPI file, most of the Actions, Triggers and References are already specified. Depending on how much effort you put into creating an OpenAPI file, you either do not need to do anything or introduce just minor adjustments. I encourage you to define action requests and responses in detail – this way Power Automate will be able to suggest particular fields during flow creation.

o365 6 - Creation of Custom Connector for Power Automate – BugHerd API connector

o365 7 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 5: Custom connector wizard in Power Automate – Definition

It is also possible to add new Actions or Triggers within the wizard, so you may start with a simple OpenAPI file and complete all actions during registration.

o365 8 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 6: Custom connector wizard – Adding a new Action or Trigger

If you feel better dealing with the code than clicking (I certainly do!), wizard provides a built-in Swagger Editor, where you may specify all aspects of action and trigger details.

o365 9 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 7: Custom connector wizard in Power Automate – Swagger Editor

If you create a connector from scratch using UI, it is also useful to do a little cleanup and extract commonly used parameter types and move them to ‘definitions’ section of a swagger definition file. This makes the definition file more concise and easier to maintain (if BugHerd decides to change a schema of one of the types, change will be needed, but in one place only).

o365 10 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 8: Swagger definition of custom connector – definitions section

When all actions and triggers for the connector are defined, the last tab Test allows for a quick verification if everything works as expected. This is also a moment to save your connector.

o365 11 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 9: Custom connector wizard in Power Automate – Test

Custom Connector usage

All right! So we have a connector defined. How can we use it then? Very simple. Once we registered the connector, trigger became available for usage within a flow designer.

o365 12 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 10: BugHerd trigger in a flow designer

As did actions:

o365 13 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 11: BugHerd actions in flow designer

After the first adding of BugHerd action or trigger, we were asked to create a BugHerd connection. As mentioned earlier, BugHerd uses basic authentication, so we needed to get a user and a password. According to BugHerd API documentation, an API key should be used as a username key, and ‘x’ as a password. We got API Key from BugHerd site in Settings -> General Settings section:

o365 14 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 12: API Key in BugHerd general settings

 

o365 15 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 13: Configuration of BugHerd connection

Unfortunately, not everything went as planned. After creating the first flow that was used by BugHerd trigger, Power Automate wrote that there is an issue with the trigger.

o365 16 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 14: Issue with BugHerd trigger

A quick inspection of BugHerd webhook creation endpoint and Microsoft documentation showed that the creation of a trigger for Power Automate will not be possible. This is due to the fact, that response to a POST call to /api_v2/webhooks.json endpoint does not return a ‘Location’ header needed by Power Automate to unregister webhook upon flow deletion or deactivation. Until BugHerd adds this header piece, we are forced to use a built-in HTTP Webhook trigger instead.

o365 17 - Creation of Custom Connector for Power Automate – BugHerd API connector

Figure 15: Response missing ‘Location’ header

Actions, however, worked like a charm 😊

For everyone interested, we have set up a github repo, where you may find an OpenAPI definition (may be used to create a custom connector in your environment) and an example flow (that tests most of the actions from custom connector). Feel free to use it until BugHerd decides to publish an official connector.

5 / 5
Kategorie: Office 365

Imię i nazwisko (wymagane)

Adres email (wymagane)

Temat

Treść wiadomości

Zostaw komentarz