How to Publish a Power Platform Custom Connector

There are over a thousand connectors available for Power Automate/Power Apps/Copilot Studio and growing by the day. And the reason for the volume is anyone can publish a connector. So I wanted to take you on my journey when I published my first connector AutoReview (check it out its free and very cool). Creating your own API is easier then you think, with great free tiers, out the box generators, and guides available. Trust me, if I can create one, anyone can!

Quick call out, there is a guide provided by Microsoft (https://learn.microsoft.com/en-us/connectors/custom-connectors/submit-certification), its what I used and although good, I found it had 2 main issues that impacted me:

• Its focused around the cli, which I didn't want to use


• It references other guides/docs that are generic so sent me down the wrong path

Which is why I decided to do this blog, I would still recommend reading that guide.

Also this guide is for verified publishers, that means you own the API and not publishing someone else's. I Suspect a lot of this guide is transferable but wanted to call it out (but Im considering to publish one of them next so I will add a guide for that too if I do).

So lets dive in:

1. Before You Start


2. Creating Connector


3. Updating json


4. Creating Package


5. Submitting


6. Review/Test/Complete

1. Before You Start

There are a few things to do before you start, and the first and most important is to answer this question:

Do I need to publish it or can I just distribute the custom connector

In most cases (and in retrospect probably my use case too), distributing the custom connector is easier and with no downsides. The pros and cons for publishing vs custom are:

Pros

• Pushed out updates


• Easier for users to find


• More professional (well appears that way)


• More stable

Cons

• Additional hurdles (see this blog)


• Slow update process


• Commitment to high API uptime


• Less flexibility in connector setup


• Has to be authenticated

Once you decided to go with publishing you need 2 things:

• A Microsoft Partner Account (https://partner.microsoft.com/en-us/dashboard/account/v3/enrollment/introduction/partnership)


• Azure Tenant

Both I believe can be set up for free (my Partner account is very old, its also what I used to publish Edge Extensions and Apps to the Microsoft Store).

2. Creating Connector

The next step is the obvious one and hopefully you have already done it, build the connector, but here's the additional steps.

Deep dive into the Solution Checker, it will list all the issues that before didn't matter but now do, like:

Icon

• Create a logo of with 1:1 dimensions within a range of 100 x 100 to 230 × 230 pixels (no rounded edges).


• Use a non-transparent, nonwhite color (#ffffff) background, and not-default color (#007ee5) that matches your specified icon background color.


• Ensure the icon is unique to any other certified connector icon.


• Submit the logo in PNG format as .png.


• Set logo dimensions below 70% for the image's height & width with a consistent background.


• Ensure brand colour is a valid hexadecimal colour and shouldn't be white (#ffffff) or default (#007ee5).

Example right failed due to not enough padding of icon

Schema

The connector must have a description that is between (30 and 500 characters) and it cant use any Power Platform product names (I wanted to use Power Automate but that wasn't allowed). You should also:

• Define operation responses with an exact schema only with expected responses.


• Don't use default responses with an exact schema definition.


• Provide valid response schema definitions for all operations in the swagger.


• Empty response schemas aren't allowed except in special cases where the response schema is dynamic. This means no dynamic content is shown in the output and makers must use JSON to parse the response.


• Empty operations aren't allowed.


• Remove empty properties unless they're required.

Additional Considerations

I also recommend to not only have request & response schemas, but also make sure everything has a descriptive description. You can do this in the ui but I recommend switching to swagger view as its a lot quicker there.

And remember to ensure every description is unique, as you cant rename the parameter so its the only way to stop it being difficult to identify the right own.

vs

Also ensure you test in both the Classic and New UI, as they use can act differently. This is generally around them using the schema differently, e.g Classic usess title, new uses x-ms-summary. Also Classic defaults to required when missing the visibility parameter, where as new defaults to advanced (thats why my old version showed the required actions in Clssic, but under advanced in New).

Test Flow

You will also need to create a flow that tests your connector (as part of the publishing process). The flow should test all of your actions, be in its own solution, and have all connection references etc included.

3. Updating json

Our connector is complete, now we need to export it in a solution and add some additional data to the connector json.

In the export navigate to the connector file and copy the definition file.

Paste the file outside of the zip and open in a text editor (I normally use vs code, but Notepad++ or even plain Notepad works). You then need to add the following key/values:

"contact": {

    "name": "your contact name",

    "url": "your site contacts page",

    "email": "your support email"

}

"x-ms-connector-metadata": [

    {

      "propertyName": "Website",

      "propertyValue": "your site url"

    },

    {

      "propertyName": "Privacy policy",

      "propertyValue": "your policy url"

    },

    {

      "propertyName": "Categories",

      "propertyValue": "category,category"

    }

  ]

Once added it should look something like this:

Save the update and drag/paste it back into the solution zip file (it should confirm you want to save & replace).

4. Creating Package

Now we have our 2 solutions (one updated) we need to create the publishing zip we upload. The folder structure is:

publishPackage.zip

    -intro.md

    -Packages.zip

        -PkgAssets

            -Test Flow Solution.zip

            -Connector Solution.zip

So you need to put the 2 solutions in a folder named 'PkgAssets', then add the folder to a zip file named 'Packages'. Finally you add the Packages.zip file and the intro.md file to a zip (named what ever you want).

Whoops I forgot about the intro.md file, its a information file that is needed for the connectors GitHub repository. Microsoft provide a template and a guide here: https://learn.microsoft.com/en-us/connectors/custom-connectors/certification-submission#create-an-intromd-artifact. Mine looks like this:

Our connector is now ready to publish, time for the fun bit!

5. Submitting

Uploading apps and extensions to the Partner Centre is relatively simple, you take the zip and upload, done. But not with connectors, we need to use Azure instead, our own instance too.

That means we have 2 steps:

• Azure Storage


• Partner Centre Submission

Azure Storage

So first you need a Azure tenant, most of you will with the company that's building the connector, but if you are like me independent, you can create one off your outlook.com account. Go to https://portal.azaure.com and sign in. You will get a trial for a while, but eventually have to convert it to a full tenant. This will require a credit card, but for what we are using it for it won't cost you anything, but if you go crazy building function apps or virtual machines you will get charged, so I highly recommend setting up cost alerts just to be on the safe side https://learn.microsoft.com/en-us/azure/cost-management-billing/costs/cost-mgt-alerts-monitor-usage-spending.

The reason we need a Azure tenant is because we are going to upload the zip file to Azure and provide a SAS tokens (think of it as a sharing link API key). This means we need 3 things first, a Resource Group, a Storage account and a container (In Power Platform terms that would be an Environment, table, row (with lots of attachment columns to some how make this example work).

The guide in MSlearn is pretty cool so I wont go into to much detail but in a nutshell:

*Create Resource Group *



(all standard settings)

Create Storage Account



(standard settings and in the Resource Group you created)

Create Container



(create from Storage Account screen, set as private)

Next we need to upload our file and create the SAS token. The upload is easy, open the container and click upload, then drag and drop the zip file.

Click on the 3 dots and click 'Generate SAS'.

And this is where in MSlearn, it says you need a Delegate Key:

But they require the token to last 3 weeks, but delegated keys only allow 7 days (I tried changing limits but didn't work).

So I tried Account Key and it worked for me. Set the expiry for at least 3 weeks and then click 'Generate SAS Token and URL', and you should see both the Token and URL.

Partner Centre

Now time for the actual submission, go to the Partner Centre and select 'Market Place', and then 'New Offer', 'Power Platform Connector'.

Go to Packages and add the Blob SAS URL from Azure.

Then fill in all the other information like type and availability (simple stuff so won't go into any detail), and then click 'Review and Publish'.

6. Review/Test/Complete

First step is automated testing, this checks the connector and all the requirements. Things like the mssing x-ms-summary parameters got me, additional info for in the json file, and the all actions have none default 200 response Schemas, I suspect your milage we vary and you will either smash it first time or not like me.

I will warn you now, this stage can be painful, 2 months of constant failure for me in my most recent publishing. This was generally down to my lack of experience/skills, but still 'feels' inconsistent. You fail on a & b, you fix a & b, but now you fail on c (even though it never changed). Even worst you fail on something that passed before (and is in production). Like I said, if I was better at API schema's this would probably be a breeze, but if you are a novice, no matter how great the support is, this is painful, and enough to put you off ever publishing a connector again.

The good news the fail report is generally descriptive of the issue, and there is even a MS form you can click and submit the issue you have when its not, then you get a response from support team with precise guidance on how to fix.

the link to the form is at the bottom of the failure report

Call out the support team are AMAZING, for all the challenges I created they were so helpful, thank you [email protected] team

Next you will recieve an email with username and password for a trial environment which will contain your connector.

The test environment link can be found back in the partner center.

Once in the environment you use your test solution/create new flow to test your connector.

It really important you fully test the connector, as even though it worked in your environment there might be some unexpected behaviour when deploying. As a quick tip I also found that in the test environment you might need to update the connector first, as mine was using previous parameters instead of latest.

Once you have fully tested and happy you click the deploy button and the final checks will run.

The rollout can take a few weeks, and its staggered across different geos (preview environment types first).

As I said at the end of the day I would strongly consider just shareing a custom conenctor first, as the publishing process can take a while and has some challenges, but when you get to see something you build available on the platform, its pretty dam cool 😎