Add a Nintex workflow as an Xtension

In this example, you will convert a document approval workflow into an 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., and import it into another workflow to be used as a custom 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. with a web form to request approval. Converting workflows into Xtension is useful when you want to re-use a complex workflow in other workflows.

Nintex workflows can be exported with their own OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. URL provided by Nintex Automation Cloud. This means you can create a workflow to be triggered and used by other workflows. Nintex Automation Cloud manages the security for you, making the import process simple.

Note:  Workflows that contain Xtensions cannot be imported as Xtensions.

Retrieving a response from a workflow Xtension

As Xtensions, workflows only return The return from a third-party API after a request has been made by the client. their workflow ID to the workflow that triggered them. This means that while you can send information in to a workflow Xtension, you won't receive any in return. If you need information returned from a workflow Xtension, you should either:

  • Configure it to store that information somewhere it can be retrieved, such as a Dropbox file or Microsoft SQL database.
  • Configure it to send the data to another service via a callback URL. The workflow Xtension calls the callback URL once it has completed. This callback may utilize variables from within the workflow.

Convert the workflow to an Xtension

To function as Xtensions, workflows must be configured with a Component workflow start event A task or occurrence that can trigger the start of a workflow, such as a form submission or third-party API event.. In this example, we will convert the Route and Approve Documents workflow template included in the Nintex trial into an Xtension that uses the email addresses and folders passed to it by the calling workflow.

Note:  The example workflow uses Box. If you do not have a Box account, you can replace the Box: Move a file actions with Dropbox: Move a file actions. The configuration is exactly the same.

Step 1: Copy the {Template} Route and Approve Documents workflow

  1. Click Workflows in your Nintex Automation Cloud tenancy.
  2. Find and open the {Template} Route and Approve Documents sample workflow.
  3. Save the workflow under a new name.

For more information, see Workflows.

Step 2: Remove Start event variables

Nintex Automation Cloud prevents you from removing the Start event while its variables are in use.

  1. Find and open the copy of the {Template} Route and Approve Documents workflow you created.
  2. Remove the Name and Path variables from the action configurations.
    Note: The Path variable is used in a link in the Message body of the Send an email actions. Expand the Message body field to full screen to edit the link. If you use Box, you will need to change or remove these links.
  3. Delete the Set a variable value action under the Start event.
  4. Delete all the variables from the workflow.

For more information, see Variables.

Step 3: Configure the Start event as a Component workflow

Configure the Start event to be a Component workflow, and create six start variables:

  • Email: the email address of the person requesting approval
  • Approval email: the email address to send express approval to
  • Input path: the file path of the folder the document is initially stored in
  • Rework path: the file path of the folder the document is moved to if it is rejected
  • Approved path: the file path of the folder the document is moved to if it is accepted
  • File name: the name of the file to approve

For more information, see Component workflow.

Step 4: Configure the actions

  1. In the Send an email: Workflow started action:
    • Add the Email variable to the Email addresses field.
    • Add the File name variable to the Subject and Message body fields.

    For more information, see Send an email.

  2. In the Assign a task action:
    • Configure the action to be an express approval.
    • Add the File name variable to the Task name, Subject and Message body fields.
    • Add the Approval email variable to the Assignee email address field.

    For more information, see Assign a task.

  3. In the Move a file: to Rework folder action:
    • Add a forward slash, the Input path variable, another slash and the File name variable to the File path field.
    • Add a forward slash, the Rework path variable, another slash and the File name variable to the File path field.

    For more information, see Box - Move a file.

  4. In the Move a file: to Approved folder action:
    • Add a forward slash, the Input path variable, another slash and the File name variable to the File path field.
    • Add a forward slash, the Approved path variable, another slash and the File name variable to the File path field.
  5. In the Send an email: Document rejected action:
    • Add the Email variable to the Email addresses field.
    • Add the File name variable to the Subject and Message body fields.
  6. In the Send an email: Document approved action:
    • Add the Email variable to the Email addresses field.
    • Add the File name variable to the Subject and Message body fields.
  7. Publish your workflow.
  8. Copy the OpenAPI Specification URL in the Workflow published window.

Create a test workflow

Step 1: Import the Xtension

  1. Open your Nintex Automation Cloud tenancy.
  2. Click Xtensions in the dashboard to open the Xtensions page.
  3. Click in the Private connector list.
  4. Paste the OpenAPI Specification URL you copied into the OpenAPI Specification URL.
  5. Wait for Nintex Automation Cloud to validate the file.
  6. Click Next.
  7. The Xtension does not use authorization, so click Next.
  8. Type Document Approval in the Name field.
  9. Edit the Description of the Xtension.
  10. Select or upload an icon for the Xtension.
  11. Click Publish.

Step 2: Create a workflow to trigger the approval workflow

We will create a general-purpose workflow that passes all of the fields through a web form. You could also create a more specific workflow that pre-configures the approval email address or the folders used, or even uses branching decisions to set different email addresses and folders for different departments.

  1. Click Create workflow in your Nintex Automation Cloud tenancy.
  2. Configure the Start event to be a Public web form with six text variables:
    • Email: the email address of the person requesting approval
    • Approval email: the email address to send express approval to
    • Input path: the file path of the folder the document is initially stored in
    • Rework path: the file path of the folder the document is moved to if it is rejected
    • Approved path: the file path of the folder the document is moved to if it is accepted
    • File name: the name of the file to approve

    For more information on designing forms in Nintex Automation Cloud, see Design a form.

  3. Find the Document Approval action group in the action toolbox.
  4. Drag the Route and Approve Documents action after the Start event.
  5. Configure the Route and Approve Documents with the variables from the Start event.
    Note: You do not need to add any initial or trailing forward slashes.
  6. Click Test to test the workflow.
  7. Save or publish the workflow.