Instructions on submitting your connector to Microsoft

After you've finished development of your custom connector, follow these instructions to prepare it for certification and to generate the connector files to submit to Microsoft.

Note

This topic provides information for certifying custom connectors in Azure Logic Apps, Power Automate, and Power Apps. Before following the steps in this article, ensure that you read the certification overview and register your custom connector with Microsoft.

Submission requirements

To maintain a high standard of quality and consistency among our certified connectors, Microsoft has a set of requirements and guidelines that your custom connector must adhere to for certification.

Title

  • must exist and be written in English
  • must be unique and distinguishable from any existing connector title
  • should be the name of your product or organization
  • should follow existing naming patterns for certified connectors
  • cannot be longer than 30 characters
  • cannot contain the words "API", "Connector", or any of our Power Platform product names (for example, "Power Apps")
  • cannot end in a non-alphanumeric character, including carriage return, new line, or blank space

Examples of good connector titles: "Azure Sentinel", "Office 365 Outlook"

Examples of poor connector titles: "Azure Sentinel's Power Apps Connector", "Office 365 Outlook API"

Description

  • must exist and be written in English
  • must be free of grammatical and spelling errors
  • should describe concisely the main purpose and value offered by your connector
  • cannot be shorter than 30 characters or longer than 500 characters
  • cannot contain any of the Power Platform product names (for example, "Power Apps")

Icon

  • should have a ~160 pixel by ~160 pixel logo inside of a ~230 pixel by ~230 pixel square (no rounded edges)
  • must contain a non-transparent, non-white background color that matches your specified icon background color
  • must be unique to any other certified connector icon
  • must be submitted in PNG format as icon.png

Operation and parameter summaries and descriptions

  • must exist and be written in English
  • must be free of grammatical and spelling errors
  • operation and parameter summaries should be non-full sentences, 80 characters or shorter, and contain only alphanumeric characters or parentheses
  • operation and parameter descriptions should be full, descriptive sentences, and end in punctuation
  • cannot contain any of the Power Platform product names (for example, "Power Apps")

Operation responses

  • should be defined with an exact schema only with expected responses
  • must not have default responses with an exact schema definition

Preparing the connector artifacts

Ensure that you have followed the specifications and have ensured the quality of your connector prior to certification. Failure to do so will result in delays in certification, as you'll be asked to make changes.

You'll be submitting to Microsoft a set of files called "connector artifacts", downloaded using a command line interface tool provided by Microsoft. Follow these steps to get started:

  1. Install the Power Platform Connectors CLI tool using these instructions..

  2. Sign in to the Power Platform using your command line by running: paconn login. Follow the instructions to sign in using Microsoft's Device Code process.

  3. Once authenticated, download your custom connector files.

    1. Run paconn download. Select the environment your custom connector is located in by specifying its number in the command line, and then select the custom connector name.

    2. The tool will download your connector artifacts in a folder to the file system location where you ran paconn. You should see four files in the folder: apiDefinition.swagger.json, apiProperties.json, settings.json, and the connector icon.

  4. Add the required metadata as described in the adding metadata section outlined below.

  5. Validate your custom connector files. Run paconn validate --api-def [Location of apiDefinition.swagger.json]. This tool will validate your connector definition and let you know of any errors you'll need to fix prior to submitting.

If your connector uses "OAuth" as its authentication type, add these whitelisted redirect URLs to your app.

  • https://global.consent.azure-apim.net/redirect

  • https://global-test.consent.azure-apim.net/redirect

Adding metadata

Your connector artifacts (files) must contain specific metadata describing the connector and its end service. The information provided in metadata will be published in our connector documentation and is publicly accessible by all users. Do not provide any private or confidential information and let us know through your Microsoft contact if there are any issues with providing us this information. To see how the metadata will be documented, visit any one of the connector-specific documentation pages under Connector Reference.

Publisher and Stack Owner

"Publisher" is the name of your company or organization. Provide the full company name (for example, "Contoso Corporation"). This must be in alphanumeric format.

"Stack Owner" is the owning company or organization of the backend service stack that the connector is connecting to. This must be in alphanumeric format.

File Location: apiProperties.json
Syntax: The "publisher" and "stackOwner" properties exist as top-level properties within the apiProperties.json file. Add the following highlighted line as shown. Ensure you enter the property name and schema exactly as shown.

metadata-publisher-example

Product or End Service metadata

The "contact" property describes how users can contact the product or end service support resources for assistance or troubleshooting. Provide one value for each of the following:

  • Name of your Support Team
  • URL to your Support Website
  • Support Email

"Website" is the product or end service website and gives users information on the product or end service they are using with the connector. This should be a URL.

"Privacy policy" refers to the public privacy policy of the product or end service, or its company or organization. This should be a URL.

"Categories" refer to a logical classification of your connector among, at maximum, two of the following categories: AI, Business Management, Business Intelligence, Collaboration, Commerce, Communication, Content and Files, Finance, Data, Human Resources, Internet of Things, IT Operations, Lifestyle and Entertainment, Marketing, Productivity, Sales and CRM, Security, Social Media, Website.

File Location: apiDefinition.swagger.json
Syntax: The "contact" object is a standard field defined by the OpenAPI contract under the top-level "info" property. The "Website", "Privacy policy", and "Categories" will be defined in a custom top-level extension called "x-ms-connector-metadata". Note that the "Categories" property value is a semicolin-delimited string. Add the red-lined code snippets as shown. Ensure you enter the schema exactly as shown; do not change the propertyName.

metadata-swagger-example

Sample Code Snippets

For a friendlier experience in adding your metadata, we've provided the following code snippets to copy and fill in with your information. Ensure you add the snippets to the correct files in the correct locations as described above.

    "publisher": "_____",
    "stackOwner": "_____"
    "contact": {
      "name": "_____",
      "url": "_____",
      "email": "_____"
    }
    "x-ms-connector-metadata": [
      {
        "propertyName": "Website",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Privacy policy",
        "propertyValue": "_____"
      },
      {
        "propertyName": "Categories",
        "propertyValue": "_____;_____"
      }
    ]

Note

There is a current limitation in the use of the "Stack Owner" property and our Paconn CLI tool. Read more about the limitation here.

Before submitting

Before submitting your connector for certification, ensure that:

  • you have tested your custom connector to ensure the operations work as expected (at least 10 successful calls per operation)
  • your connector naming and descriptions make sense and follow our specifications above
  • no runtime or schema validation errors appear in the Test Section of the custom connector wizard
  • no operations are missing a summary, description, or visibility information
  • your connector contains the required metadata as specified in the adding metadata section

You'll be asked to agree to our Partner Agreement and non-disclosure agreement when you submit for Microsoft certification. If you'd like to review these terms and language prior to submission, reach out to your Microsoft contact.

Submitting the connector for certification

The following instructions outline how to publish your connector to our Power Platform Connectors open source repository and then submit the commit information for certification in ISV Studio. In general, we require open sourcing as part of our certification program; reach out to your Microsoft contact if you have any concerns.

Open sourcing the connector

We ask partners to open source their connector artifacts in our public GitHub repository as part of the certification process. There are several benefits to open sourcing your connector, including:

  • Easily adding functionality to a previously out-of-the-box released, unchangeable connector.
  • Leveraging contributions from the developer community for connector enhancements and maintenance.
  • Enabling a platform for users to submit and contribute feature requests.
  • Richer tracking history for changes made to the connector.
  • Enabling collaboration for multiple developers.

You'll retain ownership of your connector, and may accept or reject any changes to your connector. Some points of clarification on our program:

  • Your connector artifacts will be stored and publicly available in our GitHub repository. You can view our existing open sourced connectors there.
  • You'll only be open-sourcing your connector files, not your API. This data is already accessible to users through the Microsoft Power Platform's public APIs.
  • No PII data or intellectual property will be stored in the repository.
  • Microsoft will include you in the CODEOWNERS file for the connector in GitHub, and any change to your connector will be managed by you.

The process to open source your connector is easy; follow these instructions to check in your connector artifacts to GitHub.

Uploading from local files

If you have been granted an exception from open sourcing, you will need to submit your connector by uploading your local connector files. Format your custom connector files into a ".zip" archive that you'll be submitting to Microsoft. Only submit archives that have passed validation and contain all four connector artifact files.

Important

When using macOS, ensure that there are only the four connector artifact files in the .zip archive. By default, macOS includes other folders/files in a .zip archive.

Submitting to ISV Studio

You'll be asked to submit your connector artifacts to the Connector certification tab in ISV Studio. Do not submit your connector until your Microsoft contact has directed you to. Ensure that you've followed all the steps above and validated your artifacts prior to submitting.

Within the Connector certification tab in ISV Studio, you will be prompted to submit your files by either specifying GitHub commit information from your open sourced connector or by uploading your zip archive you created in the previous step. During submission, you'll also be asked to specify the following information:

  • connector testing information and credentials

    • provide as much detail as possible to ensure smooth testing.
    • if your connector uses oAuth, remember to whitelist the redirect URLs as described above.
    • avoid providing an account that uses multi-factor authentication (MFA), or provide steps for the certification team to properly access the MFA-protected account
  • a support email for Microsoft to contact in case of any issues

Reach out to your Microsoft contact if you face difficulties submitting your connector artifacts.

After you've submitted your artifacts, separately attach an intro.md to the Activity Control area. This intro.md will be included in the public-facing documentation for your connector. The following Markdown example provides a template that you can use.

Provide a detailed description here, distinct from your connector's description, of the value that the connector offers users and a high-level overview of functionality that the connector supports. This description should be no more than one paragraph of eight sentences. 


## Prerequisites

Provide information about any prerequisites that are required to use this connector. For example, an account on your website, a paid service plan, and so on. 

## How to get credentials?

Provide detailed information about how a user can get credentials to leverage the connector. Where possible, this should be step-by-step instructions with links pointing to relevant parts of your website.

If your connector doesn't require authentication, this section can be removed.

## Known issues and limitations

If your connector has any known issues and limitations, include a detailed description of them here.

After you submit your connector and intro.md, you're ready to prepare for testing your connector.

Updating your submission

We ask that updates to a connector version in the process of certification but has not yet been certified, be reserved for instances where Microsoft has requested changes or you have found a critical issue which needs to be addressed before certification. If you would like to submit an update to your already certified connector, see certified connector updates.

To submit an update to a connector version in the process of certification, follow these steps:

  1. Navigate to the Connector certification tab of ISV Studio, and select your existing submission.
  2. In the window pane that opens on the right-hand side, select your most recent version.

Submitted connectors version list

  1. Select the Submit an update button on the bottom-left of the Connector Submission view.
  2. Select Confirm on the Confirm Edit prompt. Note this will reset the certification process.
  3. Remove your existing connector archive by selecting Remove. Use either the GitHub integration to ingest the updated artifacts from the open source repository or upload the updated zip archive.

Remove existing zip archive

  1. Fill in the fields in the submission form. Ensure that the proper information, including testing, is provided as it applies to your latest update.
  2. Select the Submit for Review button on the bottom-left of the Connector Submission view. You will then see the below confirmation and we will begin the review process.

Submission received confirmation

Important

You should not select Submit an update again after completing step 7, as this will reset progress once more.