Events
Powerful Devs Conference and Hack Together
Feb 12, 11 PM - Feb 28, 11 PM
Join the online conference and 2-week hackathon to explore building powerful solutions with Power Platform.
Register nowThis browser is no longer supported.
Upgrade to Microsoft Edge to take advantage of the latest features, security updates, and technical support.
One way to create custom connectors for Azure Logic Apps, Microsoft Power Automate, or Microsoft Power Apps is to provide an OpenAPI definition file, which is a language-agnostic, machine-readable document that describes your API's operations and parameters. Along with OpenAPI's out-of-the-box functionality, you can also include the following OpenAPI extensions when you create custom connectors for Logic Apps and Power Automate:
summary
x-ms-summary
description
x-ms-visibility
x-ms-api-annotation
x-ms-operation-context
x-ms-capabilities
x-ms-trigger
x-ms-trigger-hint
x-ms-notification-content
x-ms-notification-url
x-ms-url-encoding
x-ms-dynamic-values and x-ms-dynamic-list
x-ms-dynamic-schema and x-ms-dynamic-properties
The following sections describe these extensions.
Specifies the title for the action (operation).
Applies to: Operations
Recommended: Use sentence case for summary
.
Example: "When an event is added to calendar" or "Send an email"
"actions" {
"Send_an_email": {
/// Other action properties here...
"summary": "Send an email",
/// Other action properties here...
}
},
Specifies the title for an entity.
Applies to: Parameters, response schema
Recommended: Use title case for x-ms-summary
.
Example: "Calendar ID", "Subject", "Event Description"
"actions" {
"Send_an_email": {
/// Other action properties here...
"parameters": [{
/// Other parameters here...
"x-ms-summary": "Subject",
/// Other parameters here...
}]
}
},
Specifies a verbose explanation about the operation's functionality or an entity's format and function.
Applies to: Operations, parameters, response schema
Recommended: Use sentence case for description
.
Example: "This operation is triggered when a new event is added to the calendar", "Specify the subject of the mail"
"actions" {
"Send_an_email": {
"description": "Specify the subject of the mail",
/// Other action properties here...
}
},
Specifies the user-facing visibility for an entity.
Possible values: important
, advanced
, and internal
Applies to: Operations, parameters, schemas
important
operations and parameters are always shown to the user first.advanced
operations and parameters are hidden under an additional menu.internal
operations and parameters are hidden from the user.Note
For parameters that are internal
and required
, you must provide default values.
Example: The See more and Show advanced options menus are hiding advanced
operations and parameters.
"actions" {
"Send_an_email": {
/// Other action properties here...
"parameters": [{
"name": "Subject",
"type": "string",
"description": "Specify the subject of the mail",
"x-ms-summary": "Subject",
"x-ms-visibility": "important",
/// Other parameter properties here...
}]
/// Other action properties here...
}
},
Used for versioning and life cycle management of an operation.
Applies to: Operations
family
—A string denoting the operation family folder.revision
—An integer denoting the revision number.replacement
—An object containing the replacement API information and operations."x-ms-api-annotation": {
"family": "ListFolder",
"revision": 1,
"replacement": {
"api": "SftpWithSsh",
"operationId": "ListFolder"
}
}
Used for simulating the firing of a trigger to enable testing of a trigger-dependent flow.
Applies to: Operations
"x-ms-operation-context": {
"simulate": {
"operationId": "GetItems_V2",
"parameters": {
"$top": 1
}
}
When used on the connector level, this is an overview of the capabilities that are offered by the connector, including specific operations.
Applies to: Connectors
"x-ms-capabilities": {
"testConnection": {
"operationId": "GetCurrentUser"
},
}
When used on the operation level, this is used to identify that the operation supports chunking upload and/or static chunk size, and can be provided by the user.
Applies to: Operations
chunkTransfer
—A Boolean value to indicate whether chunk transfer is supported."x-ms-capabilities": {
"chunkTransfer": true
}
Identifies whether the current operation is a trigger that produces a single event. The absence of this field means this is an action
operation.
Applies to: Operations
single
—Object responsebatch
—Array response"x-ms-trigger": "batch"
A description of how to fire an event for a trigger operation.
Applies to: Operations
"x-ms-trigger-hint": "To see it work, add a task in Outlook."
Contains a schema definition of a webhook notification request. This is the schema for a webhook payload posted by external services to the notification URL.
Applies to: Resources
"x-ms-notification-content": {
"schema": {
"$ref": "#/definitions/WebhookPayload"
}
},
Identifies in a Boolean value whether a webhook notification URL should be placed in this parameter/field for a webhook registration operation.
Applies to: Parameters/input fields
"x-ms-notification-url": true
Identifies whether the current path parameter should be double URL-encoded double
or single URL-encoded single
. The absence of this field indicates single
encoding.
Applies to: Path parameters
"x-ms-url-encoding": "double"
Dynamic values are a list of options for the user to select input parameters for an operation.
Applies to: Parameters
Note
A path string is a JSON pointer that doesn't contain the leading forward slash. So, this is a JSON pointer: /property/childProperty, and this is a path string: property/childProperty.
There are two ways to define dynamic values:
Use x-ms-dynamic-values
Name | Required | Description |
---|---|---|
operationId | Yes | The operation that returns the values. |
parameters | Yes | An object that provides the input parameters that are required to invoke a dynamic-values operation. |
value-collection | No | A path string that evaluates to an array of objects in the response payload. If value-collection isn't specified, the response is evaluated as an array. |
value-title | No | A path string in the object inside value-collection that refers to the value's description. |
value-path | No | A path string in the object inside value-collection that refers to the parameter value. |
"x-ms-dynamic-values": {
"operationId": "PopulateDropdown",
"value-path": "name",
"value-title": "properties/displayName",
"value-collection": "value",
"parameters": {
"staticParameter": "<value>",
"dynamicParameter": {
"parameter": "<name of the parameter to be referenced>"
}
}
}
Note
It's possible to have ambiguous parameter references when using dynamic values. For instance, in the following definition of an operation, the dynamic values reference the field id, which is ambiguous from the definition because it's not clear whether it references the parameter id or the property requestBody/id.
{
"summary": "Tests dynamic values with ambiguous references",
"description": "Tests dynamic values with ambiguous references.",
"operationId": "TestDynamicValuesWithAmbiguousReferences",
"parameters": [{
"name": "id",
"in": "path",
"description": "The request id.",
"required": true
}, {
"name": "requestBody",
"in": "body",
"description": "query text.",
"required": true,
"schema": {
"description": "Input body to execute the request",
"type": "object",
"properties": {
"id": {
"description": "The request Id",
"type": "string"
},
"model": {
"description": "The model",
"type": "string",
"x-ms-dynamic-values": {
"operationId": "GetSupportedModels",
"value-path": "name",
"value-title": "properties/displayName",
"value-collection": "value",
"parameters": {
"requestId": {
"parameter": "id"
}
}
}
}
}
}
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object"
}
},
"default": {
"description": "Operation Failed."
}
}
}
x-ms-dynamic-list
There's no way to reference parameters unambiguously. This feature might be provided in the future. If you want your operation to take advantage of any new updates, add the new extension x-ms-dynamic-list
along with x-ms-dynamic-values
. Also, if your dynamic extension references properties within parameters, you have to add the new extension x-ms-dynamic-list
along with x-ms-dynamic-values
. The parameter references that point to properties must be expressed as path strings.
parameters
—This property is an object where each input property of the dynamic operation being called is defined with either a static value field or a dynamic reference to the source operation's property. Both of these options are defined in the following.
value
—This is the literal value to be used for the input parameter. In the following example, the input parameter of the operation GetDynamicList operation named version is defined by using a static value of 2.0.
{
"operationId": "GetDynamicList",
"parameters": {
"version": {
"value": "2.0"
}
}
}
parameterReference
—This is the full parameter reference path, starting with the parameter name followed by the path string of the property to be referenced. For example, the input property of the operation GetDynamicList named property1, which is under the parameter destinationInputParam1, is defined as a dynamic reference to a property named property1 under parameter sourceInputParam1 of the source operation.
{
"operationId": "GetDynamicList",
"parameters": {
"destinationInputParam1/property1": {
"parameterReference": "sourceInputParam1/property1"
}
}
}
Note
If you want to reference any property that's marked as internal with a default value, you have to use the default value as a static value in the definition here, instead of parameterReference
. The default value from the list isn't used if it's defined by using parameterReference
.
Name | Required | Description |
---|---|---|
operationId | Yes | The operation that returns the list. |
parameters | Yes | An object that provides the input parameters required to invoke a dynamic list operation. |
itemsPath | No | A path string that evaluates to an array of objects in the response payload. If itemsPath isn't provided, the response is evaluated as an array. |
itemTitlePath | No | A path string in the object inside itemsPath that refers to the value's description. |
itemValuePath | No | A path string in the object inside itemsPath that refers to the item's value. |
With x-ms-dynamic-list
, use parameter references with the path string of the property you're referencing. Use these parameter references for both the key and the value of the dynamic operation parameter reference.
{
"summary": "Tests dynamic values with ambiguous references",
"description": "Tests dynamic values with ambiguous references.",
"operationId": "TestDynamicListWithAmbiguousReferences",
"parameters": [
{
"name": "id",
"in": "path",
"description": "The request id.",
"required": true
},
{
"name": "requestBody",
"in": "body",
"description": "query text.",
"required": true,
"schema": {
"description": "Input body to execute the request",
"type": "object",
"properties": {
"id": {
"description": "The request id",
"type": "string"
},
"model": {
"description": "The model",
"type": "string",
"x-ms-dynamic-values": {
"operationId": "GetSupportedModels",
"value-path": "name",
"value-title": "properties/displayName",
"value-collection": "cardTypes",
"parameters": {
"requestId": {
"parameter": "id"
}
}
},
"x-ms-dynamic-list": {
"operationId": "GetSupportedModels",
"itemsPath": "cardTypes",
"itemValuePath": "name",
"itemTitlePath": "properties/displayName",
"parameters": {
"requestId": {
"parameterReference": "requestBody/id"
}
}
}
}
}
}
}
],
"responses": {
"200": {
"description": "OK",
"schema": {
"type": "object"
}
},
"default": {
"description": "Operation Failed."
}
}
}
The dynamic schema indicates that the schema for the current parameter or response is dynamic. This object invokes an operation that's defined by the value in this field, dynamically discovers the schema, and displays the appropriate user interface for collecting user input or shows the available fields.
Applies to: Parameters, responses
This image shows how the input form changes, based on the item that the user selects from the list:
This image shows how the outputs change, based on the item that the user selects from the dropdown list. In this version, the user selects Cars:
In this version, the user selects Food:
Note
A path string is a JSON pointer that doesn't contain the leading forward slash. So, this is a JSON pointer: /property/childProperty, and this is a path string: property/childProperty.
There are two ways to define dynamic schema:
x-ms-dynamic-schema
:
Name | Required | Description |
---|---|---|
operationId | Yes | The operation that returns the schema. |
parameters | Yes | An object that provides the input parameters that are required to invoke a dynamic-schema operation. |
value-path | No | A path string that refers to the property that has the schema. If not specified, the response is assumed to contain the schema in the root object's properties. If specified, the successful response must contain the property. For an empty or undefined schema, this value should be null. |
{
"name": "dynamicListSchema",
"in": "body",
"description": "Dynamic schema for items in the selected list",
"schema": {
"type": "object",
"x-ms-dynamic-schema": {
"operationId": "GetListSchema",
"parameters": {
"listID": {
"parameter": "listID-dynamic"
}
},
"value-path": "items"
}
}
}
Note
There might be ambiguous references in the parameters. For instance, in the following definition of an operation, the dynamic schema references a field named query, which can't be deterministically understood from the definition—whether it's referencing the parameter object query or the string property query/query.
{
"summary": "Tests dynamic schema with ambiguous references",
"description": "Tests dynamic schema with ambiguous references.",
"operationId": "TestDynamicSchemaWithAmbiguousReferences",
"parameters": [{
"name": "query",
"in": "body",
"description": "query text.",
"required": true,
"schema": {
"description": "Input body to execute the request",
"type": "object",
"properties": {
"query": {
"description": "Query Text",
"type": "string"
}
}
},
"x-ms-summary": "query text"
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"x-ms-dynamic-schema": {
"operationId": "GetDynamicSchema",
"parameters": {
"query": {
"parameter": "query"
}
},
"value-path": "schema/valuePath"
}
}
},
"default": {
"description": "Operation Failed."
}
}
}
Connector | Scenario | Link |
---|---|---|
Ticketing | Get schema for details of a selected event | Ticketing |
x-ms-dynamic-properties
:
There's no way to reference parameters unambiguously. This feature might be provided in the future. If you want your operation to take advantage of any new updates, add the new extension x-ms-dynamic-properties
along with x-ms-dynamic-schema
. Also, if your dynamic extension references properties within parameters, you have to add the new extension x-ms-dynamic-properties
along with x-ms-dynamic-schema
. The parameter references that point to properties must be expressed as path strings.
parameters
—This property is an object where each input property of the dynamic operation being called is defined with either a static value field or a dynamic reference to the source operation's property. Both of these options are defined in the following.
value
—This is the literal value to be used for the input parameter. In the following example, the input parameter of the GetDynamicSchema operation named version is defined with a static value of 2.0.
{
"operationId": "GetDynamicSchema",
"parameters": {
"version": {
"value": "2.0"
}
}
}
parameterReference
—This is the full parameter reference path, starting with the parameter name followed by the path string of the property to be referenced. For example, the input property of the operation GetDynamicSchema named property1, which is under the parameter destinationInputParam1, is defined as a dynamic reference to a property named property1 under parameter sourceInputParam1 of the source operation.
{
"operationId": "GetDynamicSchema",
"parameters": {
"destinationInputParam1/property1": {
"parameterReference": "sourceInputParam1/property1"
}
}
}
Note
If you want to reference any property that's marked as internal with a default value, you have to use the default value as a static value in the definition here, instead of parameterReference
. The default value from the schema isn't used if it's defined by using parameterReference
.
Name | Required | Description |
---|---|---|
operationId | Yes | The operation that returns the schema. |
parameters | Yes | An object that provides the input parameters that are required to invoke a dynamic-schema operation. |
itemValuePath | No | A path string that refers to the property that has the schema. If not specified, the response is assumed to contain the schema in the root object. If specified, the successful response must contain the property. For an empty or undefined schema, this value should be null. |
With x-ms-dynamic-properties
, parameter references can be used with the path string of the property to be referenced, both for the key and the value of the dynamic operation parameter reference.
{
"summary": "Tests dynamic schema with ambiguous references",
"description": "Tests dynamic schema with ambiguous references.",
"operationId": "TestDynamicSchemaWithAmbiguousReferences",
"parameters": [{
"name": "query",
"in": "body",
"description": "query text.",
"required": true,
"schema": {
"description": "Input body to execute the request",
"type": "object",
"properties": {
"query": {
"description": "Query Text",
"type": "string"
}
}
},
"x-ms-summary": "query text"
}],
"responses": {
"200": {
"description": "OK",
"schema": {
"x-ms-dynamic-schema": {
"operationId": "GetDynamicSchema",
"parameters": {
"version": "2.0",
"query": {
"parameter": "query"
}
},
"value-path": "schema/valuePath"
},
"x-ms-dynamic-properties": {
"operationId": "GetDynamicSchema",
"parameters": {
"version": {
"value": "2.0"
},
"query/query": {
"parameterReference": "query/query"
}
},
"itemValuePath": "schema/valuePath"
}
}
},
"default": {
"description": "Operation Failed."
}
}
}
Create a custom connector from an OpenAPI definition
We greatly appreciate feedback on issues with our connector platform, or new feature ideas. To provide feedback, go to Submit issues or get help with connectors and select your feedback type.
Events
Powerful Devs Conference and Hack Together
Feb 12, 11 PM - Feb 28, 11 PM
Join the online conference and 2-week hackathon to explore building powerful solutions with Power Platform.
Register nowTraining
Learning path
Use advance techniques in canvas apps to perform custom updates and optimization - Training
Use advance techniques in canvas apps to perform custom updates and optimization
Certification
Microsoft Certified: Dynamics 365: Finance and Operations Apps Developer Associate - Certifications
Implement and extend finance and operation apps in Microsoft Dynamics 365.
Documentation
Create a custom connector from scratch
Learn how to use the 'create from blank' option to create a custom connector for Power Automate and Power Apps.
Overview about creating custom connectors for supporting and expanding integration scenarios.
Create a custom connector from an OpenAPI definition
Learn how to use an OpenAPI definition to create a custom connector for Azure Logic Apps, Power Automate, and Power Apps.