How I Make Power Platform Independent Publisher Custom Connectors

How I Make Power Platform Independent Publisher Custom Connectors

Earlier in the summer, I submitted a number of connectors to a new Microsoft program, the Independent Publishers connector program . Inspired by presentations by Natalie Pienkowska and Daniel Laskewitz, and my coworker Matthew Devaney's blog posts, part 1 and part 2, it is time for me to share how I created a connector that has now been submitted.

There are lots of cats in tech demos

In my house, we have two dogs, both adopted wire-haired terrier mixes. Growing up, I didn't have any pets as I was highly allergic. When my son was a toddler, he loved dogs (he even called himself a dog for most of a year), so I started getting shots which worked wonders for my dog allergies, but not so much for my cat allergies. Right now I live in a modest house in the suburbs, but one day I hope to have a little farm with sheep and an Irish wolfhound to watch over them. So if you've ever been in a client demo I've led, there has probably been a wolfhound or two.

irish-wolfhounds-16.jpg

Picking an API

Depending on whether you've built a Power Platform custom connector before or not, one of the first things I look through the documentation for is what authentication is required. Keep in mind, that custom connectors can have no authentication or one of three other authentication types:

image.png

Most free APIs use either no authentication or an API key, with paid services usually using basic authentication or OAuth 2.0. Whenever possible, if OAuth is one of the ways to authenticate, use that - it is the securest method. Other methods of authentication are a different story and you may be forced not to use a custom connector (I'm looking at you, Last.fm).

Who wants to see puppies?

In chatting about the Independent Publishers program with Matthew, I shared an API I had found for cats. I jokingly said I should do one for dogs, and he mentioned Placedog.net. Glancing over the short documentation page, it was easy for me to choose it as an after-hours project. There's no authentication method needed and a limited number of possible actions.

I highly recommend Matthew's first blog post above for a step-by-step guide to creating your first custom connector. So I'm going to skip to creating the actions for Placedog.

brave_ay8ThSHkEV.png

As you can see, there really are only three actions needed to cover all of the API options - a set width photo, a set width and height photo, and a set width and height photo with a filter (I figure setting both is a more typical use case and chose not to do a set width with filter - first to contribute gets a gold star). In the path, you can see the needed width and height parameters, with a query ID parameter if you want to request a specific photo. The filter action has an additional path parameter which I used a static dropdown to limit the selectable options to just what is available:

image.png

There is one part of the API that I am still working on and that is the random query parameter. Most query parameters can be added directly as part of the template import, but this parameter is slightly different in that there isn't a key required, e.g. ?parameter=key. C# is not a language I'm fluent in, but I used the DocuSign script example to come up with the following, though I'm getting a non-descriptive internal error:

public class Script : ScriptBase
{
    public async Task UpdateRequest()
    {
        UriBuilder uriBuilder = new UriBuilder(this.Context.Request.RequestUri + "?random");
        this.Context.Request.RequestUri = uriBuilder.Uri;
    }
}

If you see my error, please contribute the solution (another gold star opportunity!).

Testing the API is easy since you don't need to gather an API key or credentials, and there's no lengthy JSON response with additional detail fields (I do wish there was a field that includes who to credit):

brave_AQ4nqS6gJ9.png

Turn this custom connector into an Independent Publisher connector

You'll now need to use the Power Platform Connectors CLI to download the connector from your environment. Once the files are downloaded, you can get rid of the icon.png and settings.json files - you don't need to submit those. You should open both JSON files in an editor and I can't recommend Visual Studio Code enough. You'll potentially need to spend a lot of time with the apiDefinition.swagger.json file depending on how completely you detailed each parameter, and Replace is your new best friend to help fill in repeated empty fields. You'll also want to go back to the CLI and run the validate command to see what you need to fix. In my case, I was getting some errors related to a missing x-ms-url-encoding field for my path parameters. This field is not part of the custom connector UI, so you'll likely see this error, too. So find a path parameter in your Swagger file and copy the in field like, and then you'll just add that plus the x-ms-url-encoding line in Replace, click Replace All, and you're done.

Code_MkHjyHWFNM.png

Run the validate command again and make sure you don't have any errors left. After you submit the connector, it will validate the swagger file before certification, so it must be free of errors. Some warnings returned by the CLI cannot be fixed, it is just part of the peculiarities of Swagger 2.0, but most can be.

The next tool I use is the NPM swagger-markdown package. Run this script in your connector folder against the apiDefinition.swagger.json file and it will create a .md file with the same name.

cmd_bmrqtlOAav.png

I then open this in Github Atom. You'll also need the following template for your readme.md file:

# Title
Required. One paragraph, two to three sentences about the service and the connector​.

## Publisher: Publisher's Name
Required for Independent-Publisher-Connector and should be a first and last name of an individual or it can be a company name. ​If there is more than one publisher, please separate the names with a comma.​

## Prerequisites
Required. Any plans or licenses, tools requried from the connector.​

## Supported Operations
Required. Describe actions, triggers, and other endpoints.​
### Operation 1
Description of operation 1.

### Operation 2
Description of operation 2.

## Obtaining Credentials
Required. Explain the authentication method and how to get the credentials.​

## Getting Started
Optional. How to get started with your connector.

## Known Issues and Limitations
Required. Include any known issues and limitations a user may encounter.

## Frequently Asked Questions
Optional. Include frequently asked questions by your customer.
### Question 1
Answer to question 1
### Question 2
Answer to question 2

The Markdown file from swagger-markdown I open in the left frame, the markdown.md file with the template in middle, and Markdown preview in the right. What I'm looking for in the left frame are the summary and description lines to copy into the actions of the templates.

atom_7mVB1zSzPM.png

Here's what it looks like when it is all done:

atom_1pfHxzWv1v.png

When all three connector files are done, I add them to a folder with the API name. After you've forked the connectors repo, make a branch with the API name. You'll then go into the independent-publisher-connectors folder and upload your files. By already having them in a folder, you can just drag the folder and it will create the subfolder for you.

Time to contribute

It is now time to open a pull request. You'll need to gather a couple of screenshots proving you have run the actions in a Power Automate and then check the boxes confirming that the connector is ready to be reviewed.

msedge_yf9fEr56Gt.png

Once it is submitted, it'll get added to the Pull Request for the Microsoft repo. You'll get notifications from the validation team as they review your connector and when it is merged.

Final thoughts

This is by far the smallest API I've built a connector for, but it still took me 5-6 to build everything out, test the actions, and submit it. But once merge, hundreds if not thousands of developers in the community will use your connector (and hopefully some will help you maintain it). This certainly won't be the last connector I submit, but I'll leave placecat.net to Matthew.

P.S. If you can't wait until the Placedog connector is released, you can download it from my repo.