ARTICLE AD
Introduction
100 XP
12 minutes
This module explores custom connectors and explains how to configure and use them with Microsoft Power Apps, Microsoft Power Automate, and Microsoft Azure Logic Apps.
In this module, you'll:
Learn about the role of custom connectors.
Build a connector and use it in a Power Automate flow.
Connectors help make it easier for app and flow makers to connect to other apps, data, and devices in the cloud in the following ways:
Connection is done in a consistent, repeatable way that is discoverable by makers.
Connectors have actions that allow makers to control when an operation is performed.
Connectors can have triggers that allow automation to start when the triggering event occurs.
A connector is a proxy, or a wrapper, around an API that allows Power Automate, Power Apps, and Logic Apps to communicate with the underlying service. Many connectors are predefined and available for use without you having to define anything. These built-in connector definitions include services from Microsoft and others. When the service or API that you want to use doesn't have a prebuilt connector, you can create your own custom connector. If a prebuilt connector doesn't expose all triggers and actions that you need from the API, you can build a custom connector in addition to the available one to handle these extra requirements. After the custom connector has been defined, it becomes available for use when you're building apps and flows in that environment, similar to the built-in connectors.
Identify or build the API
Your first task is to check the connector reference to determine if a suitable connector already exists for the API/service. If a suitable connector doesn't already exist, then you can make your own custom connector. You can define the custom connector to describe any REST API that is public (one that is available on the internet) or private (one that is only on your internal network). Private APIs require the on-premises data gateway to access internal resources.
If a compatible API doesn't already exist, developers can build one by using any technology of choice that is capable of hosting a REST API, including Microsoft Azure Functions and Azure App Services. You can also use Azure API Management to increase manageability and governance of the APIs.
Describe the API
For Power Apps and Power Automate to discover what triggers and actions are available from the API, you must identify them when you create your custom connector. You can accomplish this task by manually editing the connector definition in the maker portal or by importing a definition in a supported format. This process includes identifying the authentication requirements for the API.
Use the connector
After they've been created in an environment, custom connectors can be used in the same way as built-in connectors. These connectors can also be used in an environment other than the one that you used to create it. The connector definition needs to be exported from the environment where it was created and then imported into any environment that needs it. You can also share the connector with other people to allow them to use it like other shared resources.
Certify and share the connector as an open source
Because custom connectors are only available in environments where their definition exists, they aren't available to other Microsoft customers. By sharing a custom connector definition as an open source, you make it available on GitHub for other customers to import into their environments. By certifying your connector, you can make the custom connector that you created available as a prebuilt connector in all customer environments. Certifying a connector requires that you own the API or have explicit permission to publish a connector from the API owner.
For more information, see Certification process.
This step in the process is optional and only required if you want to share your connector and have it listed as certified. Internal-facing connectors don't need to complete this certification process.
Describe the connector
To define a connector's actions and triggers, you need to describe the connector. A custom connector can be defined by describing only the API triggers and actions that you need. For example, if an API has 100 actions and 10 triggers that are available, you could build a custom connector with a single action. You can also describe later as your needs change.
When you describe the API, you'll use at least one of the following approaches. If you choose to import an OpenAPI definition, you can still manually manipulate your connector's definition in the portal.
Manually create in the portal - When using this approach, you would use the API documentation and examples of inputs and outputs and then define each action and trigger. This approach is good for simple APIs where you don't have the ability to import the definition. You can also use this approach to refine the definitions after you import them.
Import OpenAPI definition - OpenAPI is a specification that describes REST, simplifying the tasks of developing and consuming an API by effectively mapping all resources and operations that are associated with it. Many services/APIs publish an OpenAPI definition, and you can import it to describe the API in the custom connector. Importing version 2.0 is supported, but version 3.0 isn't currently supported. This approach is beneficial if an OpenAPI definition is available from the API publisher or, if you're developing the API, you can publish one.
Import from GitHub - Import connectors from the Power Platform Connectors repository. This is the best approach when there's already a connector published in the repository and you want to import it to modify or use it as a custom connector.
Export from Azure - If your API is built as an Azure App Service, Microsoft Azure Functions, or is managed by Microsoft Azure API Management, you can export from those services and it will automatically create the initial custom connector definition.
Work with authenticated APIs
The custom connector architecture supports working with authenticated APIs. When you define the custom connector, you'll identify how it should authenticate to the API. Authentication choices support anonymous, password protected, OAuth 2.0, and API key access.
No authentication - This choice is for APIs that allow anonymous access, and it's the default if you don't configure a specific authentication type.
Basic authentication - This choice is for APIs that require a user and password to be sent with each request.
OAuth 2.0 - OAuth 2.0 is the industry-standard protocol for authorization. This option can be configured for any API that uses OAuth 2.0. Prebuilt configurations are available for you to select from for Microsoft services like Microsoft Entra ID, GitHub, and Azure DevOps. Similar prebuilt configurations are available for other services like Dropbox, Slack, Stripe, and more. The prebuilt configurations simplify what you need to provide to configure the identity provider.
API key - An API key is a token that a client provides when making API calls. The API publisher typically provides the key, and it must be included in each request from the custom connector.
Custom connectors help make it easier for app and flow makers to use APIs/services. Mostly, makers could directly invoke the API without a connector; however, they would have to know how to compose the request and interpret the results and then handle authentication. This process would have to be completed each time the app or flow used custom connectors.
Additionally, it's not always easy for a maker to achieve the ability of having custom connectors that include triggers that enable flows to be started by events. Custom connectors help you more easily discover how to use actions and their results when you're building an app or flow that uses the connector.
The next unit explains how to build a custom connector.
Next unit: Demo of the maker portal experience
Demo of the maker portal experience
100 XP
7 minutes
You can build a custom connector in the maker experience. The following video demonstrates how to add and build a custom connector in this module's solution for a pet store.
Next unit: Explore custom connector configuration options
Explore custom connector configuration options
This unit continues explaining the basics of custom connectors by taking an in-depth look at some available configuration options.
Connector naming and general information
One of the first decisions that you'll make is the name of your connector. The name should be unique and clarify what the connector is to the consumer. You're limited to 30 characters for this name, and you can elaborate more in the Description field. The Icon background color field can also help you visually identify your connector. These fields are important because they show when the user is selecting the connector to use, and these visual cues help a user work more efficiently. If you plan to submit your connector for certification, make sure that you review the stricter requirements in the Instructions on submitting your connector to Microsoft documentation.
Action and trigger naming
After a user has narrowed down to your connector, they'll pick an action or trigger to use from the connector. The Operation ID, Summary, and Description fields help you describe each action and trigger. The operation ID is used internally, must be unique, and can't contain spaces. Using camel case, such as GetInvoice, will help simplify your ability to read the ID if you're looking at markup for the definition. The lack of spaces in names can be difficult for makers who use screen readers, but using camel case will help make your definitions more accessible for them.
The Summary field is important because it shows up in the list of actions and triggers when you're selecting the one to use. We recommend that you're descriptive enough so that you can tell what the action or trigger does. For example, the GetInvoice action description could be Get a specific invoice by ID. Frequently, makers will find the action by searching, so having descriptive names can help them find the right action quickly.
The following image shows where the summary and description elements are used when you select an action or trigger.
After you've selected an action or trigger, you'll be able to see both summary and description elements on each action card in the designer.
In the previous images, notice that the naming patterns are inconsistent, where some names have spaces in the summary and some don't. You can fix that error by updating the fields in the portal or, if you own the API, you can ask the developer to update what they provide on the OpenAPI definition that you import. Be aware that if you manually make changes in the portal and then import the OpenAPI definition again, it will overwrite your changes.
Action visibility
You can set the Visibility option on an action to influence how the action will show in the maker experience.
None - This option is the default. The action will display normally.
Advanced - The action will be available but not prioritized.
Internal - The action will be hidden.
Important - The action will be prioritized and will show first.
For example, if you import an Open API definition with 10 actions, and you don't want users to see/use two of them initially, you could select the internal option to hide them. This approach is a useful way to handle operations that are used to support dynamic connector metadata. It can also allow you to hide the actions initially and then make them visible later as users request them. Hiding the actions would keep the list that's visible to users as minimal as possible.
Actions that are selected as important are shown first. The user needs to select the connector to show any that are selected as none or advanced. This approach is best used when you have numerous actions and many aren't frequently used.
Request
The request defines what parameters/data will be passed into the operation when the action invokes the operation on the API. When you import an Open API definition, it will configure the request query, headers, and body settings. You can also import manually by importing from the sample.
The following image shows an example of what the screen looks like when you're looking at the definition.
This configuration is important because it translates into what the user sees when they use the action.
By editing each of the parameters, or by having the API developer provide more details, you can make the user experience better when you're using the action. Selecting the ellipsis (...) on each parameter will show you the following edit screen.
The fields and options that you should review and change are:
Name - Don't change; this field must match what the API is expecting.
Summary - Make this field user-friendly, for example, toDate would be To Date.
Description - This field contains a sentence that describes the parameter. It will be used as a placeholder text for the field.
Default value - This field is an optional default value, but it must be provided if you set visibility to internal and make the parameter required.
Is required - Make sure to set this option if API requires a value. This option enables a visual red asterisk next to the field.
Visibility - This parameter works like the visibility option on the previously discussed action. If you have parameters that aren't used often, select the advanced option.
Type and Format - Make sure that these fields are appropriate because the parameter that's importing from samples makes assumptions that aren't always correct.
Dropdown type - Use this parameter to configure a static or dynamic list of values to help make user selection easier and more predictable.
The following image shows an example of what the screen would look like after you fix the From Date parameter.
Response
The response defines what you expect to be returned from the API. Unlike the request, which has only a single definition, you can have different responses based on the HTTP status. For example, if your API call generates an error, the body will contain the error details instead of whatever your API returns. You can also have a default response, which is a catch-all response if one isn't available for a specific HTTP status.
Selecting one of the responses will reveal the details and, similar to the process with a request, you can edit these items for easier consumption.
The items in the response correspond to what shows in the Dynamic content panel.
Similar to the request, make sure that you've included good names and descriptions because they can help make using the values easier.
Validation
Notice that a validation section similar to the following image appears at the bottom of the screen.
Make sure that this screen doesn't show errors, and then take the time to resolve issues that are listed.
Other settings
There are also other settings such as triggers, references, and policies that aren't covered in-depth in this module.
Triggers can be configured if the API supports either polling or webhook events. When defined, triggers allow you to use your connector as the trigger for a Power Automate flow.
References define reusable parameters and are typically created when you import the definition and it defines a reusable parameter. References can also be handcrafted by using the built-in swagger editor.
Policies can be used to change the behaviors of actions and triggers. Policies are created by using one of the prebuilt policy templates.
These advanced topics are covered in detail later in this learning path.
Next unit: Exercise - Create a new connector in a solution
Exercise - Create a new connector in a solution
In this exercise, you'll create your first custom connector for an existing API called Contoso Invoicing.
Important
Use a test environment with Microsoft Dataverse provisioned. If you don't have a test environment, you can sign up for the Power Apps Community Plan.
Task 1: Review the API
To review the API, follow these steps:
Go to Contoso Invoicing.
Select the documentation link.
Review the available operations.
Select to expand and review each operation.
Close the documentation browser tab or window.
Select the Open API definition link.
The following image shows an example of the OpenAPI version of what was shown on the documentation page. Right-click and select Save as.
Save the file locally. You'll use this file later in the exercise.
Close the definition browser tab or window.
Select the API Key link.
Copy and save your API key because you'll need it later.
Select Return to home.
Select Download Logo.
Save the logo image locally; you'll use it later.
Task 2: Create a new solution
To create a new solution, follow these steps:
Go to Power Apps maker portal and make sure that you are in the correct environment.
Select Solutions > + New solution.
Enter Contoso invoicing for the Display name, select CDS Default Publisher for Publisher, and then select Create. When you're working on a real project, it's best to create your own publisher.
Don't navigate away from this page after selecting Create.
Task 3: Create a new connector
To create a new connector, follow these steps:
Open the Contoso invoicing solution that you created.
Select + New > Automation > Custom connector.
Enter Contoso invoicing for the Connector name and then select to Upload the image.
Select the connector logo image that you downloaded in Task 1: Review the API.
Enter #175497 for Icon background color.
Enter Contoso Invoicing API for Description.
Enter contosoinvoicingtest.azurewebsites.net for Host.
Select Create connector.
Don't navigate away from this page.
Task 4: Import the OpenAPI definition
To import the OpenAPI definition, follow these steps:
Select the arrow next to Connector Name.
Select the ellipsis (...) button of the connector and then select Update from OpenAPI file.
Select Import.
Select the swagger.json file that you downloaded in Task 1: Review the API and then select Open.
Select Continue.
Fill in the host URL as contosoinvoicingtest.azurewebsites.net and then select Security.
Notice that the field is filled out from the imported file.
Don't navigate away from this page.
Task 5: Review and adjust definitions
To review and adjust definitions, follow these steps:
Select the Definition tab.
Take a few minutes to review the operations that were imported.
Notice the orange triangle next to GetInvoice that indicates a warning.
Select the GetInvoice operation.
Notice that the operation indicates a missing Summary.
Enter Get Invoice as the Summary to improve the usability.
Notice the blue information circle on the PayInvoice operation and that it indicates a missing Description.
Enter Pay an invoice as the Description.
Delete both NewInvoice operations because you won't use them.
Select the GetInvoiceSchema operation.
Modify the Visibility option to internal so that people don't see it in their action list.
Select Update connector.
Don't navigate away from this page.
Task 6: Test the connector
To test the connector, follow these steps:
Select the Test tab.
Select + New connection.
Paste in the API Key that you saved in Task 1: Review the API and then select Create connection.
Select the Refresh button.
Select ListInvoiceTypes > Test Operation.
You should see some invoice data in the body area.
Next unit: Use a custom connector
Use a custom connector
Custom connectors can be used by Power Apps, Power Automate, and Azure Logic Apps. After you've selected a custom connector, using it is no different than using a built-in connector. To use the custom connector with Power Apps and Power Automate, you must configure or deploy it in the same environment where you're building your apps and flows. If you know that it is a custom connector, the quickest way to add triggers or actions from it is by selecting the Custom tab because it will show only the custom connectors in the environment. From the environment, you can select triggers and actions like you would a built-in connector.
Ensure that your custom connector actions and triggers have a descriptive summary so that users can more easily find it with the search feature.
The first time that you use the custom connector in your app or flow, you'll be prompted to provide the app key or credentials, depending on the connector's authentication type. This action will establish a connection with the connector that can be reused if you use the connector again in the same environment.
If you want to use your custom connector in other environments, make sure that you deploy or configure the custom connector in each of those environments. A common example of this scenario would be having a development, test, and production set of environments for your project.
You can choose from the following options to deploy the custom connector into each of the environments:
Download and import - From the list of custom connectors, you can select the download icon and then download the open API definition. This downloaded open API definition file can be used to import into another environment to create a custom connector, similar to the way you would have originally created this definition if you had imported from Open API. If using this option, you must still provide some configuration in the target environment to get the custom connector fully created. You would choose this option most frequently when you don't have the ability to use a solution.
Solutions - Custom connectors that are created in the context of a solution, such as the connector that you created in the previous exercise, can be exported and imported into another environment for reuse. After the solution has been imported, no extra configuration of the connector is required. This option requires Microsoft Dataverse to be available in the source and target environments. This option provides the most robust application lifecycle management (ALM) capability, including the ability to use build automation tooling for deployment.
Command line - By using Microsoft Power Platform Connectors Command Line Interface (CLI), you can also download and import the custom connector definitions. For more information, see Microsoft Power Platform Connectors CLI. You would use this option when you want to automate the manual download and import process and aren't using solutions. Additionally, you can use this option when preparing your connector for certification and sharing it as an open source. For custom connectors using solutions you can also use the Power Platform CLI to perform similar operations, see Microsoft Power Platform CLI.
To use the same custom connector for an app in Azure Logic Apps, make sure that you recreate the connector in your Azure subscription. This task can be accomplished by using the download or the previously mentioned command-line interface approach. During the creation process of the Azure Logic Apps custom connection, you'll be prompted to import the OpenAPI file that you downloaded. After the custom connector has been configured, you can use it in Azure Logic Apps in the same way that you would use it in Power Apps or Power Automate.
Next unit: Exercise - Use a connector from Power Automate
Exercise - Use a connector from Power Automate
In this exercise, you'll create a manually triggered Power Automate cloud flow that will use the Contoso invoicing custom connector that you created in the previous exercise in this module.
Important
Complete the Exercise: Create a new connector in a solution unit before starting this exercise.
Task 1: Create a Power Automate cloud flow
In this task, you'll create a Power Automate flow inside the Contoso invoicing solution that you previously created.
Get an API key from Contoso Invoicing.
[
Select the API Key link.
Copy and save your API key because you'll need it later.
Note
If you still have the API key that you previously used, it would still be usable at this time. If not, you can get a new one.
Go to Microsoft Power Platform maker portal and select the environment that you used in the Exercise: Create a new connector in a solution unit.
Select Solutions and then select to open the Contoso invoicing solution.
Select + New > Automation > Cloud flow > Instant.
Name the flow Email invoice list, select Manually trigger a flow, then Create.
Select + New step.
Select the Custom tab and then select the Contoso invoicing custom connector. Using the Custom tab to locate custom connectors is the fastest way to find them.
Select List invoices for the action.
Important
Leave the List Invoices* fields blank. This will allow us to pull all the information.
Enter Invoice connection as Connection name.
Paste your API Key. and select Create
Select Flow check to confirm there are no mistakes.
Select Save.
Select the arrow button located next to the flow name.
Select OK if prompted.
Don't navigate away from this page.
Task 2: Test the cloud flow
In this task, you'll test the cloud flow that you created in Task 1: Create a Power Automate cloud flow.
Open the Email invoice list cloud flow if not already open.
Select Run.
Select Continue.
Select Run flow.
Select Done.
Refresh the run history.
The flow run should succeed.
Next unit: Check your knowledge
Answer the following questions to see what you've learned.
Which of the following authentication types isn't supported by custom connectors?
Anonymous
Cookie Authentication
While a valid authentication pattern, Cookie Authentication isn't supported by custom connectors.
API Key
OAuth 2.0
You have built a custom connector and want to make it available to other companies, similar to built-in connectors. What should you do?
Share the connector in the portal.
Submit the connector for certification.
After it has been certified, your connector will be available to all customers in their own environments.
Publish your connector on Microsoft AppSource.
Publish the connector on GitHub as an open source.
It isn't possible to use open-source connectors in the same way as built-in ones.
You've imported an OpenAPI definition and it included 10 actions. For now, two actions shouldn't be visible to users of the connectors, but you might make them available later. What should you do to implement this preference?
Add words (HIDDEN) to the actions' names.
Select them as internal.
This selection prevents the actions from showing but retains their definition for future use.
Share only the actions that you want people to use.
Disable access to actions in a security role.
