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

In this example, you will add the x-ntx-dynamic-values Specification ExtensionA 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.

Summary

Some operationsA single request to a third-party API. Operations often become actions in the workflow designer. need information from the APIA 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 parameterA 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 SpecificationA 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.

The x-ntx-dynamic-values Specification Extension

The x-ntx-dynamic-values Specification Extension is added to a parameter object, to tell Nintex Workflow 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 Workflow 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 an OAuth2.0 client ID and secret

To import the completed custom connector, 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 Workflow 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 connector into Nintex Workflow Cloud.

Create the custom connector

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 a list of tasks lists, each of which may also contain a list of items

For more information on using OAuth2 authentication, see Build a custom connector with OAuth2 authentication to create a Google task list.

 
{
  "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",
      "properties": {
        "kind": {
          "type": "string"
        },
        "updated": {
          "type": "string",
          "format": "datetime"
        },
        "id": {
          "type": "string"
        },
        "selfLink": {
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      }
    },
    "lists": {
      "type": "object",
      "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.

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

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

Step 5: Add the x-ntx-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.
  • 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.
  • The value-title property to display in the drop-down list. You must use the same property name as defined in the list definition.
  • 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.

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 Workflow 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",
      "properties": {
        "kind": {
          "type": "string"
        },
        "updated": {
          "type": "string",
          "format": "datetime"
        },
        "id": {
          "type": "string"
        },
        "selfLink": {
          "type": "string"
        },
        "title": {
          "type": "string"
        }
      }
    },
    "lists": {
      "type": "object",
      "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 to add a task to a Google Tasks tasklist

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. Nintex Workflow 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 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: 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.

To create the workflow:

  1. Click Create workflow in your Nintex Workflow 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 Workflow Cloud, see Design a form.
  3. Drag the Create Task action after the Start event.
  4. Create the connection.

  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. Publish the workflow

Step 4: Test the workflow

  1. Click Workflow in your Nintex Workflow Cloud tenancy.
  2. Click meatballs on the workflow you created.
  3. Click Manual start.
  1. Type the name of the task you want to add in the form.
  2. Click Start to create the task in Google Tasks.
  3. View your task in Google Tasks to confirm.

Next steps

Hide operations from the Workflow designer with x-ntx-visibility