Rename actions and configuration fields with x-ntx-summary

In this example, you will add the x-ntx-summary Specification ExtensionA Nintex-specific OpenAPI Specification key that allows special functionality within Nintex Xtensions. to rename the actionA task that can be performed or triggered within a workflow, such as moving a file, sending an email, or using third-party API functionality. and configuration fields of the Airport-Data custom connector.

Summary

Nintex Workflow Cloud uses the definitions in the OpenAPI SpecificationA standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. to control the names that appear on custom actions and their configuration fields.

These fields and action names are not always helpful when designing workflows. You can use the x-ntx-summary Specification Extension to rename them to something more useful, or even provide short instructions.

The complete OpenAPI Specification and icon for this example are available here.

The x-ntx-summary Specification Extension

The x-ntx-summary Specification Extension is a simply key-value pair, where the key is always x-ntx-summary, and the value is the name you want to use. It can be added to:

Nintex Xtensions also supports the Microsoft Flow format of this Specification Extension: x-ms-summary.

Rename the custom action

Step 1: Create the basic OpenAPI Specification

Use the Airport-Data OpenAPI Specification you created earlier as a starting point, or download the completed Airport-Data API example here.

 
{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Airport Data"
  },
  "host": "www.airport-data.com",
  "basePath": "/api",
  "schemes": [
    "http"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/ap_info.json": {
      "get": {
        "summary": "Get airport info",
        "description": "Get airport info",
        "operationId": "getAirportInfo",
        "produces": [
          "application/json"
        ],
        "parameters": [
          {
            "name": "iata",
            "in": "query",
            "type": "string",
            "description": "Airport code"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/airportInfo"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "airportInfo": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string"
        },
        "location": {
          "type": "string"
        },
        "country": {
          "type": "string"
        }
      }
    }
  }
}					
				
			

Step 2: Add x-ntx-summary to the HTTP method object

Inside the HTTP method object, add the x-ntx-summary key, with the value of a new name for the custom action. You can add the x-ntx-summary field anywhere within the HTTP method object.

 
"paths": {
  "/ap_info.json": {
    "get": {
      "summary": "Get airport info",
      "description": "Get airport info",
      "operationId": "getAirportInfo",
      "produces": [
        "application/json"
      ],
      "x-ntx-summary" : "Find airport information",
		
			

In the Workflow designer

In the Workflow designer, the custom action displays the new name:

Rename the parameter configuration field

Inside the parameter object, add the x-ntx-summary key, with the value of a new name for the parameter configuration field. Note that the x-ntx-summary field must be inside the individual parameter object, not in the parameters array.

 
"parameters": [
  {
    "name": "iata",
    "in": "query",
    "type": "string",
    "description": "Airport code",
    "x-ntx-summary" : "Three-letter airport code"
  }
],
		
			

In the Workflow designer

In the Workflow designer, the custom action displays the new configuration field name:

Rename the result configuration field

Inside the property objects of the responseThe return from a third-party API after a request has been made by the client. definition or response schema object, add the x-ntx-summary key, with the value of a new name for the response configuration field. Note that the x-ntx-summary field must be inside the individual object for each property, not in the properties object or schema object.

 
"definitions": {
  "airportInfo": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string",
        "x-ntx-summary" : "Airport name"
      },
      "location": {
        "type": "string",
        "x-ntx-summary" : "Airport location"
      },
      "country": {
        "type": "string",
        "x-ntx-summary" : "Airport country"
      }
    }
  }
}
		
			

In the Workflow designer

In the Workflow designer, the custom action displays the new configuration field names:

The OpenAPI Specification

This is the complete OpenAPI Specification which renames the custom action and configuration field names. You can import this custom connector and use it in your workflows. See Import the OpenAPI Specification.

 
{
  "swagger": "2.0",
  "info": {
    "version": "1.0.0",
    "title": "Airport Data"
  },
  "host": "www.airport-data.com",
  "basePath": "/api",
  "schemes": [
    "http"
  ],
  "produces": [
    "application/json"
  ],
  "paths": {
    "/ap_info.json": {
      "get": {
        "summary": "Get airport info",
        "description": "Get airport info",
        "operationId": "getAirportInfo",
        "produces": [
          "application/json"
        ],
        "x-ntx-summary" : "Find airport information",
        "parameters": [
          {
            "name": "iata",
            "in": "query",
            "type": "string",
            "description": "Airport code",
            "x-ntx-summary" : "Three-letter airport code"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "schema": {
              "$ref": "#/definitions/airportInfo"
            }
          }
        }
      }
    }
  },
  "definitions": {
    "airportInfo": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "x-ntx-summary" : "Airport name"
        },
        "location": {
          "type": "string",
          "x-ntx-summary" : "Airport location"
        },
        "country": {
          "type": "string",
          "x-ntx-summary" : "Airport country"
        }
      }
    }
  }
}					
				
			

Test the result

Step 1: Add your custom connector

Import the OpenAPI Specification you created into Nintex Workflow Cloud:

  1. Open your Nintex Workflow Cloud tenancy.
  2. Click Xtensions in the dashboard to open the Xtensions page.
  3. Click in the Custom connector list.
  4. Click Choose a file.
  5. Navigate to the OpenAPI Specification on your computer.
  6. Wait for Nintex Workflow Cloud to validate the file.
  7. Click Next.
  1. The connector does not use authorization, so click Next.
  1. Edit the Name of the connector, which becomes the name of the action group in the Workflow designer.
  2. Edit the Description of the connector. This appears in the Custom connector list in the Xtensions page.
  3. Select or upload an icon for the connector. This is displayed for each action or event in the Workflow designer
  4. Click Publish.

Step 2: View the custom action

  1. Click Create workflow in your Nintex Workflow Cloud tenancy.
  2. Scroll down the action toolbox to the Airport Data action group.
  3. Drag the Find airport information action to the canvas and open the configuration.
  4. The fields are renamed.

Next steps

Populate a drop-down field from the API using x-ntx-dynamic-values