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

In this example, you will add the x-ntx-visibility Specification ExtensionA Nintex-specific OpenAPI Specification key that allows special functionality within Nintex Xtensions. to the Google Task custom connectorA set of instructions for the Nintex Workflow Platform to use third-party API functionality with Nintex workflows. A custom connector may include workflow actions, start events, forms or file control. to hide the getLists operationA single request to a third-party API. Operations often become actions in the workflow designer. from the Workflow designer. This operation is not useful as a workflow actionA task that can be performed or triggered within a workflow, such as moving a file, sending an email, or using third-party API functionality., so we will hide it to avoid cluttering the Workflow designer.

Summary

Not all operations, parametersA piece of information passed to a third-party API during a request. or responsesThe return from a third-party API after a request has been made by the client. represent useful actions or configuration fields when designing a workflow. Some operations may be designed as internal 'helper' operations, such as retrieving values for drop-down lists, while some parameters or responses may not relate to any workflow design. To avoid cluttering the Workflow designer with actions that should not be used in workflows, the x-ntx-visibility Specification Extension allows you to hide operations from the action toolbox, and configuration fields from the action configuration.

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-visibility Specification Extension

Nintex Workflow Cloud uses the x-ntx-visibility Specification Extension to determine when to hide an action or configuration field. By defining x-ntx-visibility with a value of internal, you can hide:

  • actions
  • configuration fields for parameters
  • configuration fields for responses

Nintex Workflow Cloud displays the action and configuration field for any operation, parameter or response that:

  • does not use the x-ntx-visibility key
  • defines x-ntx-visibility with any value other than internal.

Nintex Xtensions also supports the Microsoft Flow format of this Specification Extension: x-ms-visibility. Only the internal value is supported.

Hide the operation

Step 1: Create the basic OpenAPI Specification

Use the specification you built to create a task in a Google Tasks list, or download the completed Google Tasks custom connector example here.

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

 
{
  "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"
      }
    }
  }
}		
		
		
			

Step 2: Add the x-ntx-visibility key to hide the getlists operation

In the HTTP method object of the getlists operation, add the x-ntx-visibility key with a value of internal.

 
"paths": {
  "/users/@me/lists": {
    "get": {
      "tags": [
        "Task List"
      ],
      "summary": "List Tasklists",
      "description": "List Tasklists",
      "operationId": "getlists",
      "x-ntx-visibility": "internal",
       "produces": [
        "application/json"
      ],			
			
		
			

Nintex Workflow Cloud hides the getlists operation.

Step 3: Add the x-ntx-visibility key to hide the response configuration fields

The response configuration fields are not useful to our workflow design. Add the x-ntx-visibility key with a value of internal to each of the response properties.

 
"lists": {
  "type": "object",
  "properties": {
    "items": {
      "type": "array",
      "items": {
        "$ref": "#/definitions/list",
		"x-ntx-visibility": "internal",
      }
    },
    "kind": {
      "type": "string",
	  "x-ntx-visibility": "internal"
    },
    "etag": {
      "type": "string",
	  "x-ntx-visibility": "internal"
    }
  }
},	
		
			

Nintex Workflow Cloud hides the response configuration fields.

The OpenAPI Specification

 
{
  "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",
        "x-ntx-visibility": "internal",
        "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": {
          "x-ntx-visibility": "internal",
          "type": "array",
          "items": {
            "$ref": "#/definitions/list"
          }
        },
        "kind": {
          "type": "string",
          "x-ntx-visibility": "internal",
        },
        "etag": {
          "type": "string",
          "x-ntx-visibility": "internal",
        }
      }
    },
    "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"
      }
    }
  }
}		
		
		
			

Test the result

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: View the custom action group

  1. Click Create workflow in your Nintex Workflow Cloud tenancy.
  2. Scroll down the action toolbox to the Google Tasks action group.
  3. Only the Create Task action is displayed.
  4. Drag the Create Task action to the canvas and open the configuration.
  5. The response configuration fields are hidden.

Next steps

Adapt an API with serverless functions