Import a third-party specification
A developer or administrator role is required. For information, see User roles.
If the product or service you want to connect to your workflows has released an OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. describing their API A programming interface that defines how software can be interacted with by other software., you can import that OpenAPI file as a Xtension A set of instructions for Nintex Automation Cloud to use third-party API functionality with Nintex workflows. An Xtension may include workflow actions, start events, forms or file control.. For best results, we recommend you customize the OpenAPI file before you import it.
If you are not already familiar with OpenAPI Specifications, follow the walkthrough to Build the basic structure and add the operations A single request to a third-party API. Operations often become actions in the workflow designer., parameters A piece of information passed to a third-party API during a request. and responses The return from a third-party API after a request has been made by the client. in your first specification, before attempting to customize an existing one.
Customizing an OpenAPI Specification for use as an Xtension
When you import an OpenAPI Specification, Nintex creates a workflow action A task that can be performed or triggered within a workflow, such as moving a file, sending an email, or using third-party API functionality. for every operation listed in the specification. For many APIs, this can be dozens or even hundreds of operations, most of which aren't relevant to your workflows. A published specification also often doesn't include how operations interact, such as the response of one operation providing the parameters for another.
Step 1: Identify the actions you want to use
- Examine the API documentation to choose the operations you want to be able to call in your workflow. Keep to a minimum of operations to avoid cluttering your action toolbox.
Note: The actions are displayed in the Workflow Designer's action toolbox in the order they appear in the OpenAPI Specification.
Step 2: Add workflow-friendly names and descriptions
- Open the OpenAPI Specification file in an editor such as the Swagger.io editor.
- Use summary to give each of your chosen operations an action name that will be helpful in the workflow designer.
See x-ntx-summary.
- Use summary to rename the parameters and responses so they will be clearly understood in the action panel.
- Optionally, add placeholder text to string parameters to display suggested values in the action panel.
See Step 5: Add watermark text of Define the parameters.
Step 3: Identify any additional operations you need
- Examine the parameters required for each of your chosen actions, and find ones where valid values are provided by other operations in the API. For example:
- Choosing an existing file or folder to act upon
- Choosing a tag or label from a list
- Find the operations in the OpenAPI Specification that provide the values needed in their response. For example:
- An operation that lists all files available
- An operation that lists the tags or labels that have been configured
- Use the visibility specification extension to hide these operations from the workflow designer.
See x-ntx-summary.
Step 4: Connect supporting operations using Specification Extensions
- Use dynamic-values to connect operations that provide values to operations that need those values for their parameters.
Step 5: Remove the unused operations and definitions
- Delete the operations that you are not using.
- Optionally, delete any references that are not used by the remaining operations, to keep your specification easier to maintain in future.
Step 6: Import your OpenAPI Specification
- Import your customized OpenAPI Specification and create your Xtension.