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:

• Which operation to get the values from
• The path in the responseThe return from a third-party API after a request has been made by the client. object to the values for the drop-down list
• What property to pass as the parameter to the Create Task operation
• What property to display as value in the drop-down field
• What parameters to pass to the helper operation, if any

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:

• Uses post to send a task to /lists/{tasklist}/tasks
• Sends the tasklist parameter in the pathThe part of the URL after the hostname that directs the request to a specific resources within the host. For example, the section after "example.com" in http://example.com/this/is/a/path.
• Sends the task to be added in the bodyThe part of an HTTP request or response that can contain an arbitrary amount of data, such as the content of a form or web page.
• Defines the task to be added as an object with a single property of title

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.

Pass a parameter to the operation

If you need to pass a parameter to the helper operation:

1. Add a parameters object to the x-ntx-dynamic-values object.
2. Inside the parameters object, create an object for each parameter you need to pass, using the name of the parameter as it is defined in the helper operation.
   
3. Inside the parameter object, create a key of parameter with a value of the name of the parameter as defined in the helper operation.

In the example below:

• The UpdateTasks operation allows uses to select a task to update its status.
• UpdateTasks uses x-ntx-dynamic-values with GetTasks to list the tasks that can be updated.
• GetTasks requires a parameter called tasklist. This parameter is defined in the GetTasks operation.
• To pass the parameter to GetTasks , the x-ntx-dynamic-values parameter object inside UpdateTasks declares a parameter object of tasklist. The parameter object uses the same name as the parameter defined in the GetTasks operation.

When creating the configuration fields for the Update Task custom action, Nintex Workflow Cloud uses the parameter definitions of tasklist in GetTasks to add the required field.

Copy

							
"paths": {
  "/users/{tasklist}/tasks": {
    "get": {
      "summary": "List Tasks",
      "description": "List Tasks In Tasklist",
      "operationId": "getTasks",
      "produces": [
        "application/json"
      ],
      "parameters": [
        {
          "name": "tasklist",
          "type": "string",
          "in": "path"
        }						
      ],
      "responses": {
        "200": {
          "description": "OK",
          "schema": {
            "$ref": "#/definitions/tasks"
          }
        },
      },
      "security": [
        {
          "oauth2": [
            "https://www.googleapis.com/auth/tasks"
          ]
        }
      ]
    }
  }
  "/users/task": {
    "post": {
      "summary": "Update Task",
      "description": "Update task in list",
      "operationId": "updateTasks",
      "produces": [
        "application/json"
      ],
      "parameters": [
        {
          "name": "status",
          "type": "string",
          "in": "query",													
        },
        {
          "name": "task",
          "type": "string",
          "in": "query",							 
          "x-ntx-dynamic-values": {
            "operationId": "GetTasks",
            "parameters": {
              "tasklist": {
                "parameter": "tasklist"
              }
            }
          }
        }
      ],
      "responses": {
        "200": {
          "description": "OK",
        },
      },
      "security": [
        {
          "oauth2": [
            "https://www.googleapis.com/auth/tasks"
          ]
        }
      ]
    }
  }
							
                    

Note: This OpenAPI Specification fragment is for demonstration purposes only, and is not part of the example custom connector.

 
"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.

8. Nintex Workflow Cloud detects the OAuth 2.0 security template.
9. Type the Client ID in the Client ID field.
10. Type the shared secret in the Client Secret field.
    
11. Click Next.

12. Edit the Name of the connector, which becomes the name of the action group in the Workflow designer.
    
13. Edit the Description of the connector. This appears in the Custom connector list in the Xtensions page.
    
14. Select or upload an icon for the connector. This is displayed for each action or event in the Workflow designer
    
15. 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 on the workflow you created.
   
3. Click Manual start.

4. Type the name of the task you want to add in the form.
5. Click Start to create the task in Google Tasks.
6. View your task in Google Tasks to confirm.

Next steps

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