This month’s challenge is quite extensive. It will take you some time, so maybe taking it one step at a time is a good approach. However, once you get the hang of it, you can add so much functionality to your solutions that this really is worth every second of your time.
Challenge Objectives
🎯 Learn about custom connectors
🎯 Build a custom connector yourself
🎯 Improve usability of the connector
🎯 Share your connector
NOTE: You can only create custom connectors for services that have an API available
Sharing is caring
Every service you want to build a custom connector for is different. Some use OAuth, some an API 🔑, some are documented in rich detail, some barely. This challenge will guide you through the process of building a custom connector for Rebrandly, a short URL platform. If you build a connector for a different service that you use (which I highly recommend), the exact steps would be different. In that case, you could use this challenge as a reference. If you run into some problems during developing your own connector, please use the comment section at the bottom of this page. This way we can help each other, and all learn from everyone’s process.
🤓 What Are Custom Connectors
We all use connectors in everything we do on the Power Platform. Connectors are arguably the most important aspect of the low-code movement. Without a connection to your data source you cannot do anything. Fortunately, the range of connectors continues to grow. We also know that we live in a 🔄 rapid changing world where every day new services arise that bring tremendous value to us. We could obviously wait for someone, somewhere, to somehow magically add it to the list of available connectors. But we can also build a connector ourself. These are called custom connectors.
The power of a custom connector is that you can extend the Power Platform in directions your solution requires. Custom connectors are available within the environment you deploy them. the more experienced ones (e.g. IT 💻 department) can build these connectors and make them available to business 👔 employees to build the solution they need for their job.
But why keep it just within your business? If the connector adds value to your solution it can do so for someone else too, right? People owning the underlying service were already able to make their service available as a Non-Microsoft Publisher. Luckily for us, now everyone can make their custom made connector available for everyone as an Independent Publisher. Once the connector is accepted by Microsoft everyone will be able to find and use the thing you’ve created. How cool is that. That’s exactly what we are about to do.
🛵 Build a Custom Connector
As mentioned, this challenge will show how to build a custom connector for Rebrandly, but I encourage you to select a service you use that is not available yet. If you need some inspiration, you can check out the Top requests.
Get To Know The Service
If you want to connect to a third-party service, you need some input from that service. If a service allows you to use their API’s, they probably have a developer page where you can find their documentation. As you can see below, Rebrandly has a developer page link on their website’s footer.
As you can see, the documentation Rebrandly made available looks quite detailed 👍🏻. This is exactly what you want for your first custom connector. If the service you want to build your first custom connector for doesn’t have such detailed documentation, I recommend 🔎 searching for another service. Another option is to build a Rebrandly connector yourself first and after that 💪🏻 challenge yourself on the less documented service.
Create A New Custom Connector
Go to Power Platform and use your 👨🏽💻 developer account. If you don’t have one yet, you can get it HERE.
On the left navigation bar, select Dataverse > Custom Connector.
On the right top, select New custom connector.
The dropdown shows multiple options. If you can get OpenAPI file from the service, this is the recommended way for you. This way you can skip creating definitions later yourself. Rebrandly doesn’t offer such an OpenAPI file, so we will have to make it ourselves and therefor select the Create from blank option. This is also to show how this exactly works.
You have to give you custom connector a name. We will call it Rebrandly.
General Tab
The most important textbox on this tab is the one where you specify the host. Here you must specify the URL where make all your requests. It is like the 🚪 main entrance for developers to the third-party service. in case of Rebrandly it is https://api.rebrandly.com. I found it by going to one of the actions documented. In the top you can see the URL for this action. you only need the first part. In the custom connector designer you can now select the HTTPS option and type api.rebrandly.com in the Host textbox. The base URL is just a slash (/).
The 🔧 technical part on this tab is done. A description will help users understand the capabilities of your connector, please do. I gave the following description: Create, track, and share short links with a custom domain name. This is a simple copy-paste action from their developer home page.
For good visibility you can change the color and give an icon. Note that this is only visible for the custom connector in your environment. Once you will publish it as an Independent Publisher, this will ⛔ not be used. Independent Publisher connectors all have the same icon. Here you can see a connector my friend Daniel Laskewitz made for 🎵 Spotify. The icon displayed will be the same for your Independent Publisher connector.
But if you are not interested in publishing your connector, you can do the following.
Go to the website of your service.
🔎 Search for an area where their brand color is visible.
If you are using edge, press the ellipsis > More tools > Developer tools. A tab will open on the right side that enables you to inspect the website.
Select the inspect element button on the right top (see gif below).
Select the part where the brand color is visible.
In the Styles section of the Developer tab you will see the colors this element uses.
In many cases the brand color will be the primary color. This way you have the exact color for your service.
We can also use the Developer tool to get their icon. We are searching for a icon which would fit in a square. On the Rebrandly website there is a nice Rebrandly logo in the footer at the social section. let get that one!
🔍 Inspect the logo.
Search for a URL where you can find the logo.
Open a new tab and paste in the copied URL.
Save the logo to your machine.
Upload the logo as an icon to your connector.
Save your connector and let’s go ⏩ to the next tab.
Security tab
At the General tab we filled that host textbox and we said this was the developer 🚪 main entrance. But you need some 🔑 key to open it. As you can see, there are multiple options available. You have to read the API documentation to see what the available options are for your service. Rebrandly has both API key and OAuth as an option. An 🔑 API Key is a common end easy way to do this, so this is the one that I will choose.
We can name the Parameter label API Key. This is just for humans to read. The parameter name is the part that the service reads. They expect it in a particular way. The documentation has a separate page for the API key option. It states that the parameter name must be apikey. So, let’s put that in. The last field we have to specify is the parameter location. Here we have two options. The API Key page states it can serve both options, but the documentation is made on the header version. So that sounds like the best option for us. Most services use the header version.
Now update your connector.
Connection
At this stage we specified which online door we want to use, and what type of 🗝️ key we will show. But we don’t have that key yet. The API key page shows that we can get from our Rebrandly Dashboard. This means an account has to be created. That’s what I did and below you can see I now have an API key to get in. 😎 cool.
On the Power Platform, press Connections on the left navigation pane. Here we can create a new connection. Search for the connector name you specified (in my case Rebrandly) and enter the API key in the corresponding field.
Now everything connection-wise is done.
NOTE: Many APIs have limits. It is important to be aware of those limits.
Create Your First Action
If you build a connector from scratch, the Definition tab is where you will spend the most ⏱️ time. Here you will specify the requests. The API allows you to ask a ❓ question to the service, and it will give a response. The service expects the 🙋 question in a predefined format, so it is clear for both sides what is expected. Every question is a separate action.
Rebrandly show all the available action on their API explorer page. This is super helpful for us. Let’s create our 🥇 first action, which is the Get Acount action from Rebrandly.
Create a new action.
The action page shows this is a GET request. This is a specific type of request. There are more which we will discuss later, but for readability it is helpful to have this statement in the list. That’s why you I recommend entering GetAccount at the Operation ID field. The Summary and Description will be visible in Power Automate. These are not mandatory for custom connectors, but it is recommended to do it for better usability. The Visibility is where the action will be listed. Again, it is recommended to specify this for a better user experience.
Important operations are always shown
Advanced becomes visible after clicking see more of show advanced options (you don’t want everything to be there instantly if you have many available operations).
Internal are hidden from users. This is helpful if the API needs it, but you don’t want the end-user interacting with it.
At the request section, you can select Import from sample and select the following:
At Verb, select GET because the documentation states it is a get action.
For the URL, enter the URL the documentation specifies, which is https://api.rebrandly.com/v1/account in my case.
We start with a simple operation which doesn’t require additional input from our side, so we can select import.
After our request we should get a response with the account information in it. We specify this at the Response section by doing the following:
On the Get Acount page, see what the possible responses are. The same page allows us to test the operation on their site. This is really helpful for us. You can click try it and see what the response will be that we will receive. If this is not an option for your service, don’t worry. Just update your connector, go to the Test tab of your custom connector, select your operation and select test operation. Here you will also get the response. Copy the full response.
Now let’s go back to our operation. At the response section, select the default response.
Select Import from sample. In the body, enter the copied output and select Import.
After importing it, notice that various elements will be visible in the body section of the response. These are the elements that you will be able to use in your app or flow. Again, for these elements it is recommended to specify the Title, Description and Visibility. A great way to get an overview of this JSON response, is to go to JSON DESIGNER and paste in your JSON output. It will create a diagram that is visually appealing and easier to read.
As you can see on the right side of the diagram below, almost everything linked to limits has a used and included parameter. The body of your response shows the same items, but it isn’t specified which used relates to which parent item. That will result in a bad user experience for the end user, so let’s fix that.
Update your connector.
Go back to the custom connectors overview and download your connector.
Open it in a code editing software (e.g. Visual Studio Code).
Search for limits.
Notice that limits is an object with links, domains, etc. nested into it. This way we can identify which used relates to links, which to domains, etc. We will rename them here so we will be able to identify them. Also change the description property to title. This way we will be able to identify it in the connector designer. The image below shows the adjustments.
Save the file.
On the custom connector page, select the ellipsis > Update from OpenAPI file and select the updated file on your local drive.
An Operation With Parameters
The first action was to get familiar, but it was a quite straight forward operation. Some operations have query parameters for you to filter, sort etc. to make the operation a bit more flexible. The Workspaces operation has some of these parameters, so let take our skills to the next step.
By now, you should be able to fill the General section, so please go ahead.
For the Request section, you know that we can import it from a sample. You already did this once, but this time we have parameters we want to add to our request. As you can see on the API Explorer page, there are parameters for you to will before trying. Notice that when you enter a value at the given textbox, the GET URL on the right panel changes. when you decompose this URL, you can see it is the regular get URL (in this case https://api.rebrandly.com/v1/workspaces) added with a ? and then a concatenation of parameter=value separated by an &. So, if you don’t have something like this test functionality for your service, this is how the parameters are added to our request URL. Copy the URL with all the possible parameters in the URL string.
Now select Import from sample > Select the GET verb and enter the URL at the corresponding text field > Import.
Now you can see there are four parameters at the query parameters section. Again, it is best practice to give these parameters a Summary, a Description and set the Visibility. Also make sure that the Type field in your custom connector designer corresponds to what your service is expecting.
The last step for this operation is the response. You already did this once, but now there are two possible responses. You can add both options. Make sure to name them correctly.
If you made it until here, you probably have stretched your skills 🧰. Good job! Before we move on, I think it would be nice for you to 👀 see how the end user would interact with what we have been building. So please go ahead and create a flow. Your connector will be listed under the custom tab. Select the one we just created. As you can see, the items for which you selected the advanced radio button at the Visibility parameter, are behind the Show advanced options button. You can arrange this however you prefer. Please run the flow and see how cool it is what you just created. Hopefully this will bring excitement and make you eager to 🏁 finish the rest of this challenge.
An Operation With Dynamic Dropdown
During testing you could find the parameters that you’ve specified in the flow. But all of those were textboxes. In some cases, a dropdown would be way more convenient. If the options are static, this is quite easy. But how about options that also come from the service side? That is what we will be adding to our third operation. This time, we will add the Create Link operation.
Fill everything at the General section.
Go to the API Explorer page. Once again enter all the possible parameters. This time we are dealing with body parameters instead of query parameters and a header is also an option. This is new, but we will understand it in a bit. As you can see in the preview, the body parameters are within curly brackets. Copy that section (see above).
In the custom connector designer, select POST, enter the URL and paste the copied JSON in the Body section.
There is also a Headers section. The documentation states there is a header called workspace expected, so let’s enter that. It should look like the image 👇🏻 below and you can press Import. Make sure that you set the required parameters accordingly.
Add the 200 response.
A part I want to show is how to add dynamic dropdowns to the input parameters. As you can read in the documentation, the header that we’ve added is not a mandatory field, but it is recommended to specify a workspace ID. We could run the GetWorkspaces operation, search for the item we want and give it as input. But that is not a good experience for the end-user. Go ahead and save your connector to experience how it works without a Dynamic Dropdown. Below you can see what it looks like. Nice we have this functionality, but specifying a workspace ID is too much hassle.
Go back to the custom connector designer.
Edit the Header parameter.
Select Dynamic at for the dropdown type option.
As you can see, new field will be added. Because we have already created the GetWorkspaces operation, we can retrieve the ID field here. So select that operation.
At the value field select id. Note that the service side defined name is shown. Not any other title, summary, or anything other we added to it.
At the value display name we will select the name field. This way not all workspace ID will be shown at the end-user, but the workspace name.
Update your connector.
Let’s try it again. You might have to hard refresh before changes are visible. Now you should have a dropdown in the workspace field like the gif below.
🥳 That is quite something, isn’t it? I think you have enough knowledge now to add all the operations your service has available. So go ahead and add them. It is up to you if you want to finalize each operation first before moving on to the next one, or add everything to the designer at once, download it and adjust the code, and then add the dynamic capabilities. You could also just create the operations you are interested in. It is your connector right, so it’s all up to you. The advice I do want to give is that you check which operations you can test and use. In case of Rebrandly, tags and retargeting scripts are paid features. I am on the free tier, so I only created those operations.
If you are only interested in creating a custom connector, this is the end. If you are interested in sharing this piece of art you’ve created with the rest of the world, continue reading on how to publish this connector as an Independent Publisher.
🥋 Become An Independent Publisher
The steps you should take are described on the corresponding Microsoft documentation page. I know you can read, so I won’t describe those steps in detail. I do want to add some tips that might come in handy.
Swagger Editor
Before you start adding metadata and all that fun stuff Microsoft asks you to add to the code, view your connector in the Swagger Editor. In the Costum Connector designer there is a toggle you can use to get there. If there are some errors, resolve them.
Microsoft Power Platform Connectors CLI
A CLI is a Command Line Interface. You can use this to quickly execute tasks in Command Prompt or Powershell. The Microsoft Power Platform Connectors CLI is helpful for you in this process. The most important operation for this process is the validate operation. It will allow you to check your swagger file yourself. How to install is described in the link. If you get a yellow warning during pip install paconn, you will probably end up with some errors when you want to run a paconn operation. You will have to add Python to Windows PATH, instructions can be found here.
If you run the validation and you will get some errors, you will need to resolve them. Here is a list of possible error messages and the corresponding solution for them.
Step By Step
You don’t have to make all the operations in the API available. If you are dealing with some issues you cannot resolve at this time you could skip it. Just one additional action shared with everyone is worth more than twelve within your own environment. Once you understand the whole process, you can add functionality to your connector.
🎒 Key takeaways
👉🏻 Custom Connectors can add value to your solutions
👉🏻 Documentation of the API is key for creating the custom connector
👉🏻 Share the connector you create by becoming an Independent Publisher
Kommentare