Learn best practices for string fields
This article gives general guidance for string fields within a connector for Microsoft Power Automate, Microsoft Power Apps, Microsoft Copilot Studio, and Azure Logic Apps.
Connector information
It's important that you provide basic information about your connector. To get started, follow the basic guidelines outlined in this section. Your connector's name goes in the title field. A description of your connector goes in the _description_field. Both fields appear in the info section in the OpenAPI definition (the apiDefinition.swagger.json file).
Here's some minimum requirements to follow for connector titles and descriptions:
- There's a maximum of 30 characters in the connector title.
- The connector title and description can't include the word
API. - The connector title and description can't refer to a Power Platform product or a product for which you don't own the backend APIs.
For more information about certified connector guidelines, go to the certification submission article. Refer to it for best practices.
Operations
Each path and verb in the OpenAPI definition corresponds to an operation. Properly describing the operation with each of the following strings/tags listed helps the end user use it correctly. Here's some examples of string fields for an operation:
summary shows up as the name of the operation.
Case: Sentence
Notes:
- There should be no slash ('/') in the name.
- It shouldn't exceed 80 characters.
- It shouldn't end with a non-alphanumeric character, including punctuation or space.
description shows up as the operation description when selecting the information button.
.- Case: Sentence.
- Notes: Keep short to fit in the text box. No period required if there's a single word.
operationId is the unique ID associated with the operation.
- Case: Camel (no spaces or punctuation).
- Notes: Convey the meaning of the operation, such as GetContacts or CreateContact.
The image shows how the summary—Send an email, and description—This operation sends an email message fields appear while you're creating a workflow.
Triggers versus actions
A trigger starts a workflow or process. A couple of examples are:
- Start a workflow every Monday at 3 AM
- When an object is created
Ensure your trigger summary and description fields are readable and have semantic meaning. Trigger summary is usually in the format: _When a ___________________.
Example:
| Trigger | Summary |
|---|---|
| Create | When a task is created |
| Update | When a task is updated |
| Deleted | When a task is deleted |
Trigger description is usually in the format: _This operation triggers when ________________.
Example:
- This operation triggers when a new task is added.
An action is a task to complete within your workflow, such as Send an email, Update a row, and Send a notification. Here are a few examples for action summary:
| Action | Summary |
|---|---|
| Create | Create new task |
| Read | Get Task by ID |
| Update | Update object |
| Deleted | Delete object |
| List | List all objects |
Parameters
Each operation (whether a trigger or an action) has parameters that the user gives as input. Some of the important string fields for a parameter are:
x-ms-summary shows up as the parameter name.
- Case: Title
- Notes: This string field has a limit of 80 characters
description shows up as the parameter description within the input box.
- Case: Sentence
- Notes: Keep the description short to fit text box. No period is required if there's a single word.
This image shows the parameter highlighted has Subject as the value for the x-ms-summary field and Specify the subject of the mail as the description.
Response
Each operation has a response that can be used later on in the workflow as an input to a subsequent operation. The result schema is made up of multiple properties. Some important string fields for each property are:
x-ms-summary shows up as the result property name.
- Case: Title
- Notes: Use a short name.
description shows up as the description for the result property.
- Case: Sentence
- Notes: Keep the description short and concise, with a period at the end.
In the image, the result schema from the Manually trigger a flow operation shows up when you try to add dynamic content in one of the subsequent operations in the workflow. Here, User email is the x-ms-summary and the text below it is the description for a property in the response of Manually trigger a flow operation.
Here's few important notes to consider for summary/x-ms-summary and description fields:
- Summary and description text shouldn't be the same.
- The description provides additional information to the user, such as the output format or the object the property is related to. For example: summary : ID, description: User's ID.
- For an object with nested values, the x-ms-summary of the parent name gets appended to the child.
Visibility priority
The visibility priority of the entity is specified by x-ms-visibility. If visibility isn't specified, the value is considered normal visibility. The possible values are important, advanced or internal. Entities marked as internal don't show up in the user interface.
Visibility applies to:
- Operations
- Parameters
- Response properties
Here's an example:
In the UI, entities marked as important are displayed first, things marked as advanced are hidden under a toggle (highlighted), and things marked as internal aren't displayed. The image shows an example of parameters marked as important being shown by default. You can also see parameters marked as advanced after selecting the Show advanced options button.
Provide feedback
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.