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.
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.
Once there, click on Custom Connectors page, clicked New custom connector and selected Import from OpenApi file.
This started a wizard that guided us through the whole registration process.
First, we needed to apply some general information about the connector:
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.
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.
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.
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.
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).
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.
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.
As did actions:
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:
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.
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.
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.
Leave a comment