Connector String Guidance

The following topic contains general guidance for string fields within a connector for Power Automate, Power Apps, and Logic Apps.

Connector Info

Each connector should have a title, which is the name of the connector, and a description, which describes the connector in general. This information should be specified in the title and description fields under the info section in the the OpenAPI defintition (in the apiDefinition.swagger.json file).

The following guidelines at a minimum should be followed for connector titles and descriptions:

  • There can be a maximum of 30 characters in the connector title.
  • The connector title and description cannot include the word API.
  • The connector title and description cannot refer to a Power Platform product or a product for which you do not own the backend APIs.

A higher standard of title and description field guidelines enforced for certified connectors can be found here and should be used as best practices.

Operations

Each path and verb in the OpenAPI defintition corresponds to an operation. Properly describing the operation with each of the strings/tags below helps the end user use it correctly. Some of the string fields for an operation are:

  • summary: This will show up as the name of the operation.

    • Case: Sentence
    • Notes:
      • There should be no slash ('/') in the name.
      • It should not exceed 80 characters.
      • It should not end with a non-alphanumeric character, including punctuation or space.
  • description: This will show up as the operation description when selecting the information button information (as shown in image below).

    • Case: Sentence
    • Notes: Keep short to fit in the text box. No period required in case of a single word.
  • operationId: This is the unique ID associated with the operation.

    • Case: Camel
    • Notes: Intended to convey the meaning of the operation, such as GetContacts or CreateContact.

    The image below shows how the summary (Send an email) and description (This operation sends an email message.) fields will show up in the user interface while creating a workflow.

    operations

Triggers vs Actions

A trigger starts a workflow or process. For example, "Start a workflow every Monday at 3 AM", "When an object is created", and so on.

Trigger summary and description fields should be human 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", "Send a notification", and so on. A few examples for action summary are given below:

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: This will show up as the parameter name.

    • Case: Title
    • Notes: It has a limit of 80 characters
  • description: This will show up as the parameter descrption within the input box.

    • Case: Sentence
    • Notes: Keep short to fit text box. No period required in case of a single word.

    In the image shown below, the parameter highlighted has "Subject" as the value for the x-ms-summary field and "Specify the subject of the mail" as the description.

    parameters

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 mutiple properties. Some of the important string fields for each property are:

  • x-ms-summary: This will show up as the result property name.

    • Case: Title
    • Notes: Use a short name.
  • description: This will show up as the description for the result property.

    • Case: Sentence
    • Notes: Should be short and concise, with a period at the end.

    In the image shown below, the result schema from "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

A few important notes to be considered in general for summary/x-ms-summary and description fields are:

  • Summary and description text should not be the same.
  • Description should be used to provide 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.
  • In the case of an object with nested values, the x-ms-summary of the parent name will be appended to the child.

x-ms-visibility

Determines the visibility priority of the entity. If no visibility is specified, that is considered "normal" visibility. The possible values are "important", "advanced" or "internal". Entities marked as ‘internal’ do not show up in the user interface.

Applies to:

  • Operations
  • Parameters
  • Response properties

Example: In the UI, entities marked as "important" are usually displayed first, things marked as "advanced" are hidden under a toggle (highlighted), and things marked as "internal" are not displayed. For example, as shown in the image below, parameters marked as "important" are shown by default and parameters marked as "advanced" are shown after clicking on the button "Show advanced options".

x-ms-visibility-hidden

x-ms-visibility-visible