User experience best practices guide

Follow the guidelines below to streamline your Xtension development and create easy-to-use actions that blend with the Nintex platform experience.

Tip: Check out our OpenAPI Specification quick reference for quick definitions of parameter types, authentication, file handling and Specification Extensions.

Naming Xtensions, actions, and fields

Element	Guidelines
Xtension name	Use the name of the platform your Xtension connects to. For example, Trello, rather than Trello API or Trello Xtension.
Action name	Keep to a [verb] a/an [noun] format where sensible. For example, Delete a record, Create an item. Note: Keep things clear and concise: Get manager details does not need to become Get a manager's details. Use simple verbs where possible, like get, add, delete or update. Use the existing workflow action and connector verbs where you can. For example, look at connectors such as Box, with Update a file and Get a file. Note: Describe the action accurately. Invite user to channel indicates a user is sent an invitation they can decline. Add user to channel implies they are being immediately added without input from the user. Use the verb that best describes the action's process. Generally, try to use: Add when the item being added already exists. Avoid using add to describe creating a new item. Create when the item doesn't already exist. Remove for non-destructive deletions, for example removing a member from a team, where the member's account is not deleted. Delete where the action is destructive, such as deleting a file or record. Use sentence case for your actions, where only the first word is capitalized. Do not use full stops.

Element

Guidelines

Xtension name

Use the name of the platform your Xtension connects to. For example, Trello, rather than Trello API or Trello Xtension.

Action name

Keep to a [verb] a/an [noun] format where sensible. For example, Delete a record, Create an item.

Note: Keep things clear and concise: Get manager details does not need to become Get a manager's details.

Use simple verbs where possible, like get, add, delete or update. Use the existing workflow action and connector verbs where you can. For example, look at connectors such as Box, with Update a file and Get a file.

Note: Describe the action accurately. Invite user to channel indicates a user is sent an invitation they can decline. Add user to channel implies they are being immediately added without input from the user.

Use the verb that best describes the action's process. Generally, try to use:

Add when the item being added already exists. Avoid using add to describe creating a new item.
Create when the item doesn't already exist.
Remove for non-destructive deletions, for example removing a member from a team, where the member's account is not deleted.
Delete where the action is destructive, such as deleting a file or record.

Use sentence case for your actions, where only the first word is capitalized.

Do not use full stops.

Field name

(input and output)

Use a noun (collection, file, location) rather than a verb where possible.

Note: Use your best judgment. Some exceptions exist, such as Sort by, or Overwrite file.

Use sentence case (only capitalize the first word) for field names with multiple words.

Do not use full stops.

Note: Required fields are automatically marked with an asterisk in Nintex Workflow.

Output fields

Output field labels should indicate the content that is returned, rather than "Output" or "Result". For example: Calendar item, To do list, Card.

Avoid using "details" in the output field label unless:

The returned content is metadata about the object, rather than the object itself.
Example:
- Email contains the email content body, sender and recipient list and subject line.
- Email details contains information about the email such as size, date sent, whether it was opened or bounced.

The API returns different forms of the object in different operations, and you need to distinguish between the forms.

Note: In this case, try to use a more specific word than "details" if possible to indicate the difference between the forms, and be consistent with the terms you use across operations.

If you are using objects, hide object labels that aren't helpful to the workflow designer.

Tip: Use x-ntx-summary with an empty string to hide a label for an object or array input field: "x-ntx-summary" : "".

Validating connections and fields

Where possible, provide validation for connections and fields:

Connections should be validated when created, using x-ntx-connection-validation.
Fields should be validated using properties such as pattern, min-length, and field types.
See the OpenAPI Specification quick reference.

Connections that are not validated may fail either when the action is being configured by the workflow designer (if the action uses dynamic fields) or when the workflow first runs.

Example: The workflow designer mistypes the password when they create a basic auth connection for an action that does not use dynamic fields. If the connection is not validated, the workflow fails when it runs. If the connection is validated, the workflow designer is informed of the problem when they create the connection, and can correct it.

To validate a connection on creation:

Define the operation that validates the connection in your OpenAPI Specification.
Identify the operation with an operationID. and hide it using "x-ntx-visibility": "internal".
Inside the security definition, add the x-ntx-connection-validation object.
Inside x-ntx-connection-validation, add the operationID of the validation endpoint.


{
  "paths": {
    "/validateConnection": {
      "get": {
        "operationId": "validateSecurity",
        "security": [ {"basicAuth": [] } ],
        "x-ntx-visibility": "internal",
        "responses": {
          "200": {"description": "OK"},
          "401": {"description": "Unauthorized."}
        }
      }
    }
  },
  "securityDefinitions": {
    "basicAuth": {
      "type": "basic",
      "x-ntx-connection-validation": {
        "operationId": "validateSecurity"
      }
    }
  }						
}

Adding placeholders, sub-labels and helper-text

Element	Guidelines
Placeholders	Placeholders should only be used in drop-down fields to indicate the choice to the workflow designer. Placeholder text can be: Select a value Select an operator Select a variable. Do not use verbs other than "select" (for example, do not use "choose a variable"). Do not use placeholders in text or other input fields: use sub-labels to explain required formatting or restrictions. Note: The placeholder text in the drop-downs for x-ntx-query-builder cannot be overridden.
Sub-label text	Only use sub-label text when necessary to clarify how the workflow designer should interact with the field. For example: Required field formats. Limitations on number of items. Don't use sub-label text if the information can be readily assumed from the field label. For example, an Email field does not need an explanation of what an email address looks like. Tip: Choose clear field names that don't need further explanation. Sub-label text should be a single line if possible, a maximum of two lines. Use sentence case (only the first word is capitalized). Do not use full stops unless there is more than one sentence.

Element

Guidelines

Placeholders

Placeholders should only be used in drop-down fields to indicate the choice to the workflow designer.

Placeholder text can be:

Select a value
Select an operator
Select a variable.

Do not use verbs other than "select" (for example, do not use "choose a variable").

Do not use placeholders in text or other input fields: use sub-labels to explain required formatting or restrictions.

Note: The placeholder text in the drop-downs for x-ntx-query-builder cannot be overridden.

Sub-label text

Only use sub-label text when necessary to clarify how the workflow designer should interact with the field.

For example:

Required field formats.
Limitations on number of items.

Don't use sub-label text if the information can be readily assumed from the field label. For example, an Email field does not need an explanation of what an email address looks like.

Tip: Choose clear field names that don't need further explanation.

Sub-label text should be a single line if possible, a maximum of two lines.

Use sentence case (only the first word is capitalized).

Do not use full stops unless there is more than one sentence.

Structuring actions

Where possible, workflow designers should be able to configure your action from the top of the action panel to the bottom without backtracking. When ordering the fields in the action panel, Nintex Workflow uses the following priorities in sequence:

Connection (if required).
Any required fields that are not part of an object are displayed in the order they're defined in your OpenAPI Specification.
Fields that are implicitly grouped, such as objects.
1. Within a group, any required fields will appear first, using the order they're defined in your OpenAPI Specification.
2. Optional fields are then displayed in the order they're defined in your OpenAPI Specification.
Optional fields that are not part of an object , using the order they're defined in your OpenAPI Specification.
Additional fields from helper operations that are not defined as parameters in the current operation.
Some fields, such as those that use x-ntx-dynamic-schema or x-ntx-dynamic-values, need parameters from other operations. For example, a field that requires the workflow designer to choose a ticket uses x-ntx-dynamic-values with a helper operation that lists all available tickets. If that field is also defined in the current operation, Nintex Workflow does not duplicate the field in the action panel: the value is passed through to the helper operation.
If the field is not defined in the current operation, it appears in the action panel after all of the current operation's fields, but before the output fields.
Output fields are always displayed last.

Guideline	Description
Put contextualizing fields first	Fields that specify the location or context the action is working in, such as sites, lists or file paths, should appear first.
Use Object-then-Modifier order	When an action adds or removes one object or attribute from another object, the workflow designer should select the object being modified first, and then select the modification to be made. Example: If the action is Remove member from team, the workflow designer should select the Team that will be changed first, and, then select the Member to remove. If the action is Invite user to channel, the user should select the Channel first, and then the User to invite.

Guideline

Description

Put contextualizing fields first

Fields that specify the location or context the action is working in, such as sites, lists or file paths, should appear first.

Use Object-then-Modifier order

When an action adds or removes one object or attribute from another object, the workflow designer should select the object being modified first, and then select the modification to be made.

Example:

If the action is Remove member from team, the workflow designer should select the Team that will be changed first, and, then select the Member to remove.
If the action is Invite user to channel, the user should select the Channel first, and then the User to invite.

Respect dependencies

Fields with dependencies, such as dynamic-schema or dynamic-values, should appear after the fields they require. For example, If your action requires selecting a Category and Subcategory, the Category should appear first.

Note: Some fields from the helper operation may appear after your current operation's fields.

Create logical groups

Group related fields together to help the workflow designer understand how to configure them. For example, email recipient, carbon-copy (Cc) and Blind-carbon-copy (Bcc) fields should be appear together.

Hide constant values

Fields that always have the same value should have an initial value set, and be hidden from the workflow designer.

Note: Do not use the complex object renderer ("x-ntx-render-version": 2) for your Xtension if you want to set and hide initial values. The complex object renderer uses the strict OpenAPI Specification for default, which is the value the API uses when no value is provided in the request, not an initial value.

Tip: Hide fields using x-ntx-visibility. See x-ntx-visibility.