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.
Looking for other examples?
The following examples also use x-ntx-dynamic-values:
- Create dynamic fields (x-ntx-dynamic-schema).
- Upload files by streaming.
- Upload files by URL.
- Download files by URL.
- Download base64 files.
- Upload base64 files.
- Add subscribers to Mailchimp.
Also see the how-to on x-ntx-dynamic-values.
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:
- Which operation to get the values from
- The path in the response The 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 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:
- If you do not already have a Google Developer Account, create a free account here.
- Click the following link to open the Google API console.
- Click Enable API and type Task API in the search box.
- Click Enable if this API is not already enabled.
- Click Credentials in the left hand navigation pane.
- Click Create credentials, and select OAuth client ID.
- Select Web application.
- Type Nintex Automation Cloud connector for Tasks in the Name field.
- Click Create.
- 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:
- Uses post to send a task to /lists/{tasklist}/tasks
- Sends the tasklist parameter in the path The 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 body The 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.
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.
- 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.
See operationId in the x-ntx-dynamic-values guide.
See value-path in the x-ntx-dynamic-values guide.
See value-title in the x-ntx-dynamic-values guide.
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"
}
}
]
If you need to pass a parameter to the helper operation:
- Add a parameters object to thex-ntx-dynamic-values object.
- 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.
- Inside the parameter object, create a key of parameter with a value of the name of the parameter as defined in the helper operation.
See parameters in the x-ntx-dynamic-values guide.
In the example:
- The UpdateTasks operation allows uses to select a task to update its status.
- UpdateTasks usesdynamic-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 Automation Cloud uses the parameter definitions of tasklist in GetTasks to add the required field.
Note: This OpenAPI Specification fragment is for demonstration purposes only, and is not part of the exampleXtension.
"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" ]
}
]
}
}
}
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:
- Open your Nintex Automation Cloud tenancy.
- Click Xtensions in the dashboard to open the Xtensions page.
- Click
in the Private connector list. - Click Choose a file. Navigate to the OpenAPI Specification on your computer.
- Wait for Nintex Automation Cloud to validate the file.
- Click Next.
- Nintex Automation Cloud detects the OAuth 2.0 security template.
- Type the Client ID in the Client ID field.
- Type the shared secret in the Client Secret field.
- Click Next.
- Edit the Name of the Xtension, which becomes the name of the action group in the Workflow designer.
- Edit the Description of the Xtension. This appears in the Private connector list in the Xtensions page.
- Select or upload an icon for the Xtension. This is displayed for each action or event in the Workflow designer.
- 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:
- Open the Credentials section of the Google Developer Console.
- Edit the OAuth2 credentials you created earlier.
- Paste the Redirect URL you copied into the Authorized redirect URIs field.
- 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:
- Click Create workflow in your Nintex Automation Cloud tenancy.
- 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. - Drag the Create Task action after the Start event.
- Create the connection.
For more information on connections, see Connections. - Select the Google account to connect to.
- Click Allow.
- Configure the Task List that all tasks will be added to.
- Configure the Task Title to use the public web form variable.
- Click Test to test the workflow.
- Save or publish the workflow.