Creating a Microsoft Independent Connector — step by step guide for WorldTime API
In our world, easy integration of distributed systems — let it be third party or not — is a great advantage for businesses, given it enables reuse of already tested, trusted and dedicated services without the need to build and maintain your own solution.
Power Platform connectors are wrapper solutions from Microsoft to make REST APIs available for low-code platforms so that end users without any coding knowledge could automate various business cases through clicks, e.g.: Send an email summary report and push notification of daily twitter mentions of my own hashtag.
What is an independent connector?
To promote adoption, Microsoft delivers a vast and growing number of connectors available out-of-the-box when signing up for Power Automate or Power Apps — these wrappers are maintained directly by Microsoft, kept up to date and reflect a structured way to communicate with the end services.
In case there is a service not yet available, you may directly use the generic “HTTP Connector” to communicate with your desired endpoint, however choosing this route you will lose governance possibilities, e.g.: restrict given finance services to be used only together with each other or easy overview where SAP services are targeted.
Better approach is to build Custom Connector for the not available target services and maintain the wrapper as your own resource, sharing it if needed with various users. Independent Connectors are taking this even a step further, making your own connector not only available on a per user basis, but rather for the whole Microsoft community, while taking ownership of it and receiving best practice guidance from Microsoft Engineers. Let’s take a look, how it goes - through my own experience!
Building your custom connector
First, identify your target. For me, this will be the WorldTimeAPI, providing global time zone relevant information through a public endpoint — compared to the Google solution only available through pay-as-you-go model. If you are interested in more custom examples, check out my other posts on:
- Building my Custom Connector for Facebook from scratch
- Building my Custom Connector for Microsoft Teams from scratch
Second, get familiar with it. Visit the relevant website, look around for documentation and whether they have an OpenAPI file available. Check if you can test it already through a console or directly in your browser. This is only to make you comfortable with the main requests and responses, to know, what to expect. In my case, my hello world moment was a request in my browser against http://worldtimeapi.org/api/timezone/Europe/Budapest
Third, let’s build! Log in to your Power Automate environment, create a solution and add a new Custom Connector component. I know I know, I am bit old school here, you can do all this directly without leaving the comfort of your Visual Studio Code, but bear with me, only intending to give high level ideas for now. Follow the official doc, the aim here is to put together the minimal viable product (MVP) and have successful test runs with green check marks!
In case of WorldTimeAPI, there is no need for authentication given it is a public endpoint — so after choosing name and description I can skip ahead to build the various actions. I will be leaving out one of them deliberately: WorldTimeAPI has an endpoint which guesses my local time and time zone based on my IP, however since the connector will be used by cloud services, this does not really make sense to have.
Turn it into an Independent Connector!
Implement Best Practices. What differentiates an Independent Connector from an in-house Custom Connector is that it is meant at the end for global availability, and so, needs to be implemented to meet higher standards. Following great guidance found in the documentation HERE (Coding Standards) and HERE (Best Practices), extend your first draft with descriptions, labels and well defined operations. Don’t forget to add meta information about the connector itself! Many of the data you fill out here will greatly improve end user experience when using your connector within a flow.
Verify again. Run a test or two with Power Automate to make sure all labels are grammatically correct. This is especially important given Microsoft will use translation services to localize the connector based on text used by you. Check, that the flow responses for the given operations are well structured into various data types instead of simple JSONs and that they are available to be used for subsequent flow actions. Don’t forget to check that all input and output has a full sentence apart from their title, describing their value.
Export and prepare for submission. Although you could have a shortcut to obtain the Swagger JSON by exporting the connector in a solution ZIP, in the long run the official path should be followed by installing and using the command line tool PAC, as it also provides static analysis tooling. Follow instructions for installation of python and paconn. When ready, download your connector with the interactive downloadcommand and don’t forget to run the static validation either:
paconn login
paconn download
paconn validate --api-def [Path of apiDefinition.swagger.json]
paconn logoutStart the official process
Prepare your repository. Navigate to the official GitHub repo found HERE and fork it so that you can begin working on your own version. After creating a local clone, don’t forget to create a new branch for yourself based on the DEV branch. It could seem to be a less important step — as anyways you are working against your own fork — however if you intend to work on multiple connectors, this will be a must to not create unwanted dependencies. Follow the additional steps described HERE to set up upstream repo.
Add modifications. Create a new folder for your connector, following naming conventions used and add your exported JSON files. This is also the time to create your README file describing on high level the connector, its usage and operations while adding some thoughts about its limitations too.
Submit your changes. The only thing left is to create a commit and when ready, proceeding to a pull request. You will need to attest to various statements regarding your connector and include screenshots to prove that the connector actually works. Microsoft will run automatic checks and involve official reviewers to guide you through the final steps of the process. Be aware, this may take multiple weeks!
Fail quickly but gracefully!
Now you only need patience to allow Microsoft to finish the approval and deployment process. While waiting, you can go ahead and secure your connector with basic regression tests, since now you have responsibilities for it: always stay ahead of possible hiccups!
There are many options to set up automated verification (GitHub, Azure DevOps, …) , but I find it somewhat convenient to test my connector with Power Automate itself. My basic solution looks as follows:
- Create a scheduled Power Automate flow
- Set the trigger to be daily at 00:00 UTC — or at your preferred time
- Set up the happy path test cases within a Try block
- Catch the possible errors (error or time out)
- Handle the errors by sending yourself an email notification and summary
You can even provide direct link to the failed flow run, meaning just within 2 clicks you have already full access to any information you may need in case of an issue:
Hope you enjoyed these lines and have now a better overview on the topic at hand. Let me know what are your thoughts or what connector are you missing to streamline your daily work?
You can find my Custom Connectors:
