Create drop-downs (x-ntx-dynamic-values)

In this example, you will add the x-ntx-dynamic-values Specification Extension A Nintex-specific OpenAPI Specification key that allows special functionality within Nintex Xtensions. to populate a drop-down list that allows designers to select which task list in Google Tasks they would like to add a task to.

For more information on this specification extension, see our full guide: x-ntx-dynamic-values.

Some operations A single request to a third-party API. Operations often become actions in the workflow designer. need information from the API A programming interface that defines how software can be interacted with by other software. in order to function. For example, when adding a task to a Google Tasks task list, we need to pass the id of the task list we're adding to as a parameter A piece of information passed to a third-party API during a request.. But the task list id is not information we typically know, nor is it easy to discover. To avoid having to memorize and type in the task list id when configuring the custom action, we use x-ntx-dynamic values to populate a drop-down configuration field with the available values from the API.

The complete OpenAPI Specification A standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. and icon for this example are available here.

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

Dynamic-values

The x-ntx-dynamic-values Specification Extension is added to a parameter object, to tell Nintex Automation Cloud that this parameter should be a drop-down list populated by the response of another operation. Inside the x-ntx-dynamic-values object, you define:

Note:  The helper operation must be defined within the OpenAPI Specification.

Nintex Automation Cloud creates a drop-down field for the configuration field for this parameter with the populated values.

Note: The populated drop-down field appears in the configuration settings for the custom action. It cannot be used to create a drop-down web form field.

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

Register a client ID and secret

To import the completed Xtension, you must create the client ID and shared secret in a Google Developer account:

  1. If you do not already have a Google Developer Account, create a free account here.
  2. Click the following link to open the Google API console.
  3. Click Enable API and type Task API in the search box.
  4. Click Enable if this API is not already enabled.
  5. Click Credentials in the left hand navigation pane.
  6. Click Create credentials, and select OAuth client ID.
  7. Select Web application.
  8. Type Nintex Automation Cloud connector for Tasks in the Name field.
  9. Click Create.
  10. Record the Client ID and Client Secret somewhere secure. You will need these to import the Xtension into Nintex Automation Cloud.

Create the Xtension

Step 1: Create the basic OpenAPI Specification

This is similar to the specification you created to create a task list:

  • It uses the same OAuth2 authentication
  • Instead of creating a new task list, it fetches the available task lists
  • The operation has no parameters, so use an empty parameters array
  • The operation returns an object containing tasks lists, each of which may also contain a list of items

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

For more information on using OAuth2 authentication, see Add OAuth2 authentication .

 
{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Google Tasks"
    },
    "host": "www.googleapis.com",
    "basePath": "/tasks/v1",
    "schemes": [ "https" ],
    "produces": [ "application/json" ],
    "paths": {
        "/users/@me/lists": {
            "get": {
                "tags": [ "Task List" ],
                "summary": "List Tasklists",
                "description": "List Tasklists",
                "operationId": "getlists",
                "produces": [ "application/json" ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/lists"
                        }
                    },
                    "default": {
                        "description": "Operation Failed"
                    }
                },
                "security": [
                    {
                        "oauth2": [ "https://www.googleapis.com/auth/tasks" ]
                    }
                ]
            }
        }
    },
    "definitions": {
        "list": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "kind": {
                    "type": "string"
                },
                "updated": {
                    "type": "string",
                    "format": "datetime"
                },
                "id": {
                    "type": "string"
                },
                "selfLink": {
                    "type": "string"
                },
                "title": {
                    "type": "string"
                }
            }
        },
        "lists": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "items": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/list"
                    }
                },
                "kind": {
                    "type": "string"
                },
                "etag": {
                    "type": "string"
                }
            }
        }
    },
    "securityDefinitions": {
        "oauth2": {
            "type": "oauth2",
            "flow": "accessCode",
            "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
            "tokenUrl": "https://www.googleapis.com/oauth2/v4/token",
            "scopes": {
                "https://www.googleapis.com/auth/tasks": "access to tasks"
            }
        }
    }
}

Step 2: Uniquely name the operation

We will need to refer to this operation from within the OpenAPI Specification, so make sure it has a unique ID in the operationID value.

 
"get": {
    "tags": [ "Task List" ],
    "summary": "List Tasklists",
    "description": "List Tasklists",
    "operationId": "getlists",
    "produces": [ "application/json" ]
}

Step 3: Add a second operation to create a task

Add a second operation that:

For more information on defining multiple operations, see Define the operations.

 
"/lists/{tasklist}/tasks": {
    "post": {
        "tags": [ "Task" ],
        "summary": "Create Task",
        "description": "Create Task",
        "operationId": "createtask",
        "produces": [ "application/json" ],
        "parameters": [
            {
                "name": "tasklist",
                "type": "string",
                "in": "path"
            },
            {
                "name": "task",
                "x-ntx-summary": "Task",
                "description": "Title of task",
                "in": "body",
                "schema": {
                    "$ref": "#/definitions/taskSimple"
                },
                "required": true
            }
        ],
        "responses": {
            "200": {
                "description": "OK",
                "schema": {
                    "$ref": "#/definitions/lists"
                }
            },
            "default": {
                "description": "Operation Failed"
            }
        },
        "security": [
            {
                "oauth2": [ "https://www.googleapis.com/auth/tasks" ]
            }
        ]
    }
}

Step 4: Create the definition for the task item to be added

Create a definition for the task item to be added to the task list in the definitions object.

For more information on creating definitions, see Streamline with references.

 
"taskSimple": {
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        }
    }
}

Step 5: Add the dynamic-values field to the parameter

In the tasklist parameter object, add the x-ntx-dynamic-values key. Create an object for the value, and add:

  • The operationId of the operation to use to populate the lists. This is the operationId for getTasks you created earlier.
  • See operationId in the x-ntx-dynamic-values guide.

  • The value-path property to pass the createTask operation as the tasklist parameter. You must use the same property name as defined in the list definition.
  • See value-path in the x-ntx-dynamic-values guide.

  • The value-title property to display in the drop-down list. You must use the same property name as defined in the list definition.
  • See value-title in the x-ntx-dynamic-values guide.

  • The value-collection, specifying the JSON path to the value-path and value-title in the response object. In this example, they are contained in the items object. You will need to examine the data returned from the API to complete this field.
  • See value-collection in the x-ntx-dynamic-values guide.

Note: Currently, x-ntx-dynamic-values fields are not supported in the global parameters object. See Streamline with references.

 
"parameters": [
    {
        "name": "tasklist",
        "type": "string",
        "in": "path",
        "x-ntx-summary": "Task List",
        "description": "Task List",
        "required": true,
        "x-ntx-dynamic-values": {
            "operationId": "getlists",
            "value-collection": "items",
            "value-path": "id",
            "value-title": "title"
        }
    }
]

The configuration field for the parameter now appears as a drop-down field populated by the user's Google task lists.

The OpenAPI Specification

The complete OpenAPI Specification. Import this into Nintex Automation Cloud to test it for yourself.

 
{
    "swagger": "2.0",
    "info": {
        "version": "1.0.0",
        "title": "Google Tasks"
    },
    "host": "www.googleapis.com",
    "basePath": "/tasks/v1",
    "schemes": [ "https" ],
    "produces": [ "application/json" ],
    "paths": {
        "/users/@me/lists": {
            "get": {
                "tags": [ "Task List" ],
                "summary": "List Tasklists",
                "description": "List Tasklists",
                "operationId": "getlists",
                "produces": [ "application/json" ],
                "parameters": [],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/lists"
                        }
                    },
                    "default": {
                        "description": "Operation Failed"
                    }
                },
                "security": [
                    {
                        "oauth2": [ "https://www.googleapis.com/auth/tasks" ]
                    }
                ]
            }
        },
        "/lists/{tasklist}/tasks": {
            "post": {
                "tags": [ "Task" ],
                "summary": "Create Task",
                "description": "Create Task",
                "operationId": "createtask",
                "produces": [ "application/json" ],
                "parameters": [
                    {
                        "name": "tasklist",
                        "type": "string",
                        "in": "path",
                        "x-ntx-dynamic-values": {
                            "operationId": "getlists",
                            "value-collection": "items",
                            "value-path": "id",
                            "value-title": "title"
                        }
                    },
                    {
                        "name": "task",
                        "x-ntx-summary": "Task",
                        "description": "Title of task",
                        "in": "body",
                        "schema": {
                            "$ref": "#/definitions/taskSimple"
                        },
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "schema": {
                            "$ref": "#/definitions/lists"
                        }
                    },
                    "default": {
                        "description": "Operation Failed"
                    }
                },
                "security": [
                    {
                        "oauth2": [ "https://www.googleapis.com/auth/tasks" ]
                    }
                ]
            }
        }
    },
    "definitions": {
        "list": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "kind": {
                    "type": "string"
                },
                "updated": {
                    "type": "string",
                    "format": "datetime"
                },
                "id": {
                    "type": "string"
                },
                "selfLink": {
                    "type": "string"
                },
                "title": {
                    "type": "string"
                }
            }
        },
        "lists": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
                "items": {
                    "type": "array",
                    "items": {
                        "$ref": "#/definitions/list"
                    }
                },
                "kind": {
                    "type": "string"
                },
                "etag": {
                    "type": "string"
                }
            }
        },
        "taskSimple": {
            "type": "object",
            "properties": {
                "title": {
                    "type": "string"
                }
            }
        }
    },
    "securityDefinitions": {
        "oauth2": {
            "type": "oauth2",
            "flow": "accessCode",
            "authorizationUrl": "https://accounts.google.com/o/oauth2/v2/auth",
            "tokenUrl": "https://www.googleapis.com/oauth2/v4/token",
            "scopes": {
                "https://www.googleapis.com/auth/tasks": "access to tasks"
            }
        }
    }
}

Create the workflow

Step 1: Add your Xtension

Import the OpenAPI Specification you created into Nintex Automation Cloud:

  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. Click Choose a file. Navigate to the OpenAPI Specification on your computer.
  5. Wait for Nintex Automation Cloud to validate the file.
  6. Click Next.
  1. Nintex Automation Cloud detects the OAuth 2.0 security template.
  2. Type the Client ID in the Client ID field.
  3. Type the shared secret in the Client Secret field.
  4. Click Next.
  1. Edit the Name of the Xtension, which becomes the name of the action group in the Workflow designer.
  2. Edit the Description of the Xtension. This appears in the Private connector list in the Xtensions page.
  3. Select or upload an icon for the Xtension. This is displayed for each action or event in the Workflow designer.
  4. Click Publish.

Step 2: Authorize the redirect URL

The API will only accept requests that redirect to URLs that have already been authorised for the OAuth2 credentials. To authorise the redirect URL:

  1. Open the Credentials section of the Google Developer Console.
  2. Edit the OAuth2 credentials you created earlier.
  3. Paste the Redirect URL you copied into the Authorized redirect URIs field.
  4. Click Save.

Step 3: Create the workflow

Create a workflow that prompts the user to type the task to add, and then adds it to the pre-selected task list in Google Tasks.

For more information on creating workflows, see the Workflow Designer.

To create the workflow:

  1. Click Create workflow in your Nintex Automation Cloud tenancy.
  2. Configure the Start event to be a Public web form with one text variables for the name of the new task to add.
    For more information on designing forms in Nintex Automation Cloud, see Design a form.
  3. Drag the Create Task action after the Start event.
  4. Create the connection.
    For more information on connections, see Connections.
  5. Select the Google account to connect to.
  6. Click Allow.
  7. Configure the Task List that all tasks will be added to.
  8. Configure the Task Title to use the public web form variable.
  9. Click Test to test the workflow.
  10. Save or publish the workflow.