OpenAPI Specification quick reference

You can paste and edit these definition blocks where needed to create parameters A piece of information passed to a third-party API during a request. and response The return from a third-party API after a request has been made by the client. definitions or authentication Identifying the requestor of the API using techniques such as a username and password, an API key, or OAuth2.0. types in your OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger..

Note:  These topics are based on the OpenAPI 2.0 Specification.

Action panel fields

Use the following definitions to create fields A field representing the parameter or response of the endpoint when it is configured as a workflow action in the Workflow Designer. for your actions 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. in the Workflow designer.

Description JSON 

Array

A sequence of items.

Tip: Create an array that only allows unique items using "uniqueItems" : true.

Tip: Disable variables so that workflow designers must choose from the provided options using "x-ntx-variables": false.

Default array (allows duplicates and variables).

{
  "type": "array",
  "title": "Empty sheet",
  "items": {
    "type": "string",
    "title": "Name"
  }
}

Array that enforces unique items selected from an enum and does not allow variables.

{
  "type": "array",
  "title": "Unique array",
  "x-ntx-variables": false,
  "items": {
    "type": "string",
    "enum": [ "1", "2", "Three" ]
  },
  "uniqueItems": true
}

Boolean

A Yes or No value.

 

{
  "name": "Boolean",
  "in": "query",
  "required": true,
  "type": "boolean"
}

Condition builder

Allows workflow designers to specify an OData-formatted value for a filter.

We recommend using x-ntx-dynamic-schema to retrieve the schema rather than defining a static schema.

See Create OData queries (x-ntx-query-builder).

Note: Query-builder can only be used where the API accepts OData-formatted strings.

 
                        
{
  "x-ntx-query-builder": {
    "schema": {
      ...
    }
  }
}

Date

A date.

 
{
  "type": "string",
  "format": "date",
  "title": "Date"
}

Date-Time

A date and time.

 
{
  "type": "string",
  "format": "date-time",
  "title": "DateTime"
}

Dynamic drop-down fields

Allows workflow designers to select from a set of options provided by the API.

See x-ntx-dynamic-values.

Note: Dynamic-values can only be used with APIs that provide an endpoint to retrieve the list of options.

Note: You can also create static drop-down lists. See Enum.

 

{
  "x-ntx-dynamic-values": {
    "operationId": "helperOperation",
    "value-collection": "resultObject",
    "value-path": "id",
    "value-title": "display",
    "parameters": {
      "objectName": {
        "parameter": "objectName"
      }
    }
  }
}

Dynamic fields

Allows workflow designers to select which of several fields to use in the action panel.

See x-ntx-dynamic-schema.

For an example, also see Create dynamic fields (x-ntx-dynamic-schema).

Note: Dynamic-schema can only be used with APIs that provide an endpoint to query the data schema.

 

{
  "x-ntx-dynamic-schema": {
    "operationId": "helperOperation",
    "parameters": {
      "objectName": {
        "parameter": "objectName"
       }
    },
    "value-path": "pathToResult"
  }
}

Enum

A static drop-down list.

 

{
  "name": "enum",
  "in": "query",
  "required": true,
  "type": "string",
  "enum": [
    "choice 1",
    "choice 2",
    "choice 3"
  ]
}

Tip: Use x-ntx-oneOf or to create more user-friendly labels for your enum values.

File

A file in one of the following formats:

  • URL reference
  • base64 encoded
  • streaming (form-data or binary)

See File handling for examples.

Integer

A whole number.

 

{
  "name": "integer",
  "in": "query",
  "required": true,
  "type": "integer"
}

Number

A number with a possible fractional component.

 

{
  "name": "number",
  "in": "query",
  "required": true,
  "type": "number"
}

Sort-by

A sort-by or order-by field in OData format.

We recommend using x-ntx-dynamic-schema to retrieve the schema rather than defining a static schema.

 

{
  "type": "string",
  "title": "",
  "x-ntx-orderby-builder": {
    "schema": {
      "properties": {
        "option1": {
          "name": "option1",
          "title": "Option 1"
        },
        "option2": {
          "name": "option2",
          "title": "Option 2"
        }
      }
    }
  }
}

String

Stores a sequence of characters, usually alpha-numeric.

Tip: String fields default to a single line of text. If you want to allow multiple lines of text, add the "format" : "multiline" property to the parameter.

 

{
  "name": "string",
  "in": "query",
  "required": true,
  "type": "string"
}

Tree

Display an object as a tree structure to indicate the hierarchy of properties.

This control requires x-ntx-render-version : 2. See Send arrays or complex objects.

Also see x-ntx-control.

 
{
  "type": "object",
  "additionalProperties": false,
  "x-ntx-control": "tree",
  "properties": {
    "a": {
      "type": "string",
      "title": "A"
    },
    "b": {
      "type": "string",
      "title": "B"
    }
  }
}

Note: The object does not have to be at the root level. All fields within the designated object are displayed in the tree component; any properties or objects outside the designated object, including parent properties or objects, are displayed in a flat structure.

Authentication

Use the following definitions to create authentication for your Xtensions 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. in the Workflow designer. Authentication is defined in two places:

Tip: You can request additional connection information, such as a database name, using x-ntx-connection-properties, and validate your connection when it is created using x-ntx-connection-validation.

Description JSON

Basic authentication

Authenticate with a username and password passed in the header.

See Basic authentication.

Security definition: 


"securityDefinitions": {
    "myBasicAuth": {
        "type": "basic"
    }
}

HTTP method: 


"security": [
    {
        "myBasicAuth": []
    }
]

See an example: The OpenAPI Specification

API key authentication

Authenticate with a security token passed in the header or query.

See API key authentication.

Security definition: 


"securityDefinitions": {
    "myApiKey": {
        "type": "apiKey",
        "name": "app_id",
        "in": "query"
    }
}

 

HTTP method: 


"security": [
    {
        "myApiKey": []
    }
]

See an example: The OpenAPI Specification

OAuth2 authentication

Authenticate with a client ID and shared secret to allow a user to authorize Nintex Automation Cloud to access their account without passing credentials.

Note: To use OAuth 2.0 authentication, you must register a client in the application you're connecting to. When you register your client, use the following redirect URL: https://us.nintex.io/connection/api/Token.

See OAuth 2.0 authentication.

Security definition:

Use the authentication URLs and scope paths provided by the API.


"securityDefinitions": {
    "oauth2": {
        "type": "oauth2",
        "flow": "accessCode",
        "authorizationURL": 
        "tokenURL":
        "scopes": {
            
        }
    }
}

HTTP method:

Add the scope paths you will access in the oauth2 array.

					
"security": [
    {
        "oauth2": [
            
        ]
    }
]

See an example: The OpenAPI Specification

File handling

Use the following definitions to use files as inputs and outputs of Xtensions.

Description JSON 

Streaming (Upload, multipart/form-data)

Use multipart/form-data to stream files to other services from Nintex Automation Cloud.

See Files as multipart formdata.

For an example, see Upload files by streaming.

 

"consumes": [
    "multipart/form-data"
],
"parameters": [
    {
        "in": "formData",
        "name": "file",
        "type": "file"
    }
]

See an example: The OpenAPI Specification
Streaming (Upload, application/octet-stream)

See Files as octet streams.

Use application/octet-stream to stream files to other services from Nintex Automation Cloud.

 

"consumes": [
    "application/octet-stream"
],
"parameters": [
    {
        "name": "body",
        "in": "body",
        "required": true,
        "schema": {
        "type": "string",
        "format": "binary"
        }
    }
]

Base64 (Upload)

Use base64 encoding to upload a file to other services from Nintex Automation Cloud.

See Base64 files.

For an example, see Upload base64 files.

 

"parameters": [
    {
        "name": "body",
        "in": "body",
        "required": true,
        "schema": {
            "type": "object",
            "properties": {
                "content": {
                    "type": "string",
                    "format": "byte"
                }
            }
        }
    }
]

See an example: The OpenAPI Specification

Base64 (Download)

Use base64 encoding to download a file from other services into Nintex Automation Cloud.

See Base64 files.

For an example, also see Download base64 files.

 

"produces": [
    "images/jpeg"
],
"responses": {
    "200": {
        "description": "Status 200",
        "schema": {
            "type": "object",
            "properties": {
                "file": {
                    "type": "string",
                    "format": "byte"
                }
            }
        }
    }
}

See an example: The OpenAPI Specification

File URL reference (Upload)

Upload a file to other services from Nintex Automation Cloud using a file URL.

See Files by URL reference.

For an example, see Upload files by URL

 

"parameters": [
    {
        "name": "body",
        "in": "body",
        "schema": {
            "type": "object",
            "properties": {
                "content": {
                    "type": "string",
                    "format": "x-ntx-file-reference"
                }
            }
        }
    }
]

See an example: The OpenAPI Specification

File URL reference (Download)

Download a file from other services into Nintex Automation Cloud using a file URL.

See Files by URL reference.

For an example, also see Download files by URL

 

"produces": [
    "images/jpeg"
],
"responses": {
    "200": {
        "description": "Status 200",
        "schema": {
            "type": "object",
            "properties": {
                "file": {
                    "type": "string",
                    "format": "x-ntx-file-reference"
                }
            }
        }
    }
}

See an example: The OpenAPI Specification

Overriding and overloading operations

Overriding host or basePath

If you need to define an operation that uses the same security information with a different host or base path, use x-ntx-host and x-ntx-basePath in the operation definition to override the OpenAPI Specification's root host and basePath .

See x-ntx-host.

Also see x-ntx-basePath.

 
"/examplepath": {
  "post": {
    "summary": "Post request",
    "x-ntx-host": "operation-specific-host.com",
	"x-ntx-basePath": "/operation/specific/basePath",						
    "parameters": [...],
    "responses": {...}
    }
  }
}

Overloading operations

If you need to define two versions of an overloaded endpoint (one endpoint and HTTP method serving two purposes), add a dummy query string to one of the paths in the OpenAPI Specification.

Note: This workaround is supported by Nintex Automation Cloud, but it is not valid in the OpenAPI Specification. When validating, temporarily change the operation with the dummy query to something else to validate the rest of your OpenAPI Specification. 

 
"/examplepath": {
  "post": {
    ...
  }
},
"/examplepath?method2": {
  "post": {
    ...
  }
}

OpenAPI Specification Extensions and properties

Use the following definitions to customize the behavior of your Xtension inside Nintex Automation Cloud.

Description JSON 

Additional properties

Prevent workflow designers from adding additional arbitrary properties to objects at design time using additionalProperties.

Used in: Parameters and response objects.

 
{
  "additionalProperties": false
}

Note: If additionalProperties is not defined for an object, it defaults to true, allowing workflow designers to add arbitrary properties to that object.

Control

Display the properties of an object as a nested structure rather than in a flattened hierarchy.

Used in: Object parameters only.

 
{
  "x-ntx-control": "tree"
}

Note: The object does not have to be at the root level. All fields within the designated object are displayed in the tree component; any properties or objects outside the designated object, including parent properties or objects, are displayed in a flat structure.

Dynamic-schema

Generate an operation's parameters based on a response from the API.

Used in: Dynamically-generated parameter and response objects.

See x-ntx-dynamic-schema.

For an example, also see Create dynamic fields (x-ntx-dynamic-schema).

 

{
  "x-ntx-dynamic-schema": {
    "operationId": "helperOperation",
    "parameters": {
      "objectName": {
        "parameter": "objectName"
       }
    },
    "value-path": "pathToResult"
  }
}

Note: The values used depend on the helper operation's requirements and data returned. Not all keys may be required in each case.

See an example: The OpenAPI Specification

Dynamic-values

Display a drop-down list populated by the API.

Tip: value-title and value-path can accept a path.to.property if the property is not at the root level.

Used in: Parameters.

See x-ntx-dynamic-values.

For an example, also see Create drop-downs (x-ntx-dynamic-values).

 

{
    "x-ntx-dynamic-values": {
        "operationId": "helperOperation",
        "value-collection": "resultObject",
        "value-path": "id",
        "value-title": "display",
        "parameters": {
            "objectName": {
                "parameter": "objectName"
            }
        }
    }
}

Note: The values used depend on the helper operation's requirements and data returned. Not all keys may be required in each case.

See an example: The OpenAPI Specification

One of

Create a single-select drop-down field with static options.

Used in: parameters.

 
"parameters": [{
  "in": "query",
  "name": "test",
  "type": "string",
  "x-ntx-oneOf": [
    { "const": "1", "title": "One" },
    { "const": "2", "title": "Two" },
    { "const": "3", "title": "Three" }
  ]
}]

Order-by builder

Create a sort-by or order-by field.

Used in: Order-by or sort-by parameters.

 
{
  "type": "string",
  "title": "",
  "x-ntx-orderby-builder": {
    "schema": {
      "properties": {
        ...
      }
    }
  }
}

Placeholder text

Guide your designers with placeholder text.

Used in: Parameters.

See Define the parameters.

 

{
    "description": "Email address"
}

Query-builder

Create an OData query string from a pre-defined or dynamically-retrieved schema, allowing workflow designers to specify conditions in the action panel.

Used in: OData-formatted filter parameters.

Note: This Specification Extension can only be used where the API accepts ODat-formatted strings.

See x-ntx-query-builder.

For an example, also see Create OData queries (x-ntx-query-builder).

 
                        
{
  "x-ntx-query-builder": {
    "schema": {
      ...
    }
  }
}

Tip: Use the dynamic-schema specification extension to create a filter with a dynamic schema.

See an example: The OpenAPI Specification

Required values

Use required to enforce a parameter that must be included in the request.

Used in: Required parameters

 

{
  "required": true
}
Note:  Empty strings are considered valid in the JSON schema specification. If your string parameter should not be considered valid when empty, add the property minLength with a value of 1. 
{
  "minLength": 1
}

Sublabel

Add a sub-label with additional information the workflow designer needs to complete the field.

Used in: Parameters

Requires UI-Schema.

See x-ntx-sublabel.

 

{
  "x-ntx-sublabel" : "Maximum 250 characters"
}

Subtext

Add subtext below the field with additional information the workflow designer needs to complete the field.

Used in: Parameters

Requires UI-Schema.

See x-ntx-subtext.

 

{
  "x-ntx-subtext" : "Email address or phone number"
}

Summary

Define the display name for actions and fields.

Used in: Operations, parameters and response objects.

See x-ntx-summary.

For an example, also see Rename fields (x-ntx-summary).

 

{
    "x-ntx-summary": "My New Title"
}

See an example: The OpenAPI Specification

Validated values

Use regular expressions to validate parameter values.

Used in: Parameters

See Validate with regex.

 

{
    "pattern": "^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$"
}

See an example: The OpenAPI Specification

Visibility

Hide operations and configuration fields on the Workflow designer.

Used in: Operations, parameters and response objects.

See x-ntx-visibility.

For an example, also see Hide operations (x-ntx-visibility).

 

{
    "x-ntx-visibility": "internal"
}

See an example: The OpenAPI Specification