แชร์ผ่าน


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. Screenshot that shows 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 summarySend an email, and descriptionThis operation sends an email message fields appear while you're creating a workflow.

    Screenshot that shows how the summary and description fields will appear.

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.

    Screenshot that shows the x-ms-summary and description parameter values in the interface.

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.

response

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.

Screenshot that shows a dropdown list for advanced options.

Screenshot that shows the expanded hidden advanced options.

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.