Send arrays or complex objects

Some APIs A programming interface that defines how software can be interacted with by other software. require parameters A piece of information passed to a third-party API during a request. to be structured as arrays or complex objects, which are not currently supported by Nintex Automation Cloud. You can send arrays or complex objects by configuring your OpenAPI Specification to use the complex object renderer.

Note: It is not possible to enable complex object support on a per-action A task that can be performed or triggered within a workflow, such as moving a file, sending an email, or using third-party API functionality. basis. Complex objects are enabled for the whole Xtension A set of instructions for Nintex Automation Cloud to use third-party API functionality with Nintex workflows. An Xtension may include workflow actions, start events, forms or file control.. Currently, Nintex Automation Cloud does not offer file support with complex objects.

Working with objects

When an OpenAPI Specification uses the complex object renderer, Nintex Automation Cloud displays the action configurations A field representing the parameter or response of the endpoint when it is configured as a workflow action in the Workflow Designer. as a flattened structure, allowing the designers access to all the object properties. Property names incorporate the names of their parent objects, ensuring complex structures can be navigated easily.

Note: We recommend you rename object properties using x-ntx-summary to ensure designers correctly configure the actions. You can also rename parent objects with an empty string to avoid their name appearing in child properties. See Rename fields (x-ntx-summary).

You can also control whether workflow designers can add properties not defined in the OpenAPI Specification to an object at design-time using additionalProperties.

Copy 
{
  "exampleObject": {
    "type": "object",
    "additionalProperties": false,
    "properties": {
      "ID": {
        "type": "string"
      },
      "Name": {
        "type": "string"
      }
    }
  }
}

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

Objects returned in the operation's response are represented as objects in the designer.

Example: 

In the example opposite, the object Post Contents contains the properties of:

  • Your Content Text.
  • Media Category.
  • Media Object (a collection).
  • Network Visibility.

The Output is the object returned by the operation.

 

Working with arrays

If the parameter is an array, the array is represented as a card, and the designer can add, remove and reorder sets of values as required.

How to use x-ntx-render-version

Add a key of x-ntx-render-version with the value of 2 to your OpenAPI Specification, and define your parameter objects or arrays as you normally do.

Where to use x-ntx-render-version

Add the x-ntx-render-version property at the root level of your OpenAPI Specification.

Copy
{
  "swagger": "2.0",
  "info": {
    "version": "1",
    "title": "Example API"
  },
  "host": "www.exampleAPIs.com",
  "basePath": "/API",
  "schemes": [ "https" ],
  "x-ntx-render-version" : 2,
  "produces": [ "application/json" ],
  "paths": {...}
}

Example

Tip: In the example below, the x-ntx-summary Specification Extensions has been used with an empty string value to hide the names of some parent objects.

Copy 
{
  "swagger": "2.0",
  "x-ntx-render-version": 2,
  "info": {
    "version": "1.0.0",
    "title": "LinkedIn",
    "description": "LinkedIn"
  },
  "host": "api.linkedin.com",
  "basePath": "/v2",
  "schemes": ["https"],
  "produces": ["application/json"],
  "consumes": ["application/json"],
  "paths": {
    "/me": {
      "parameters": [
        {
          "$ref": "#/parameters/LinkedInHeader"
        }
      ],
      "get": {
        "summary": "Get User Details",
        "operationId": "GetUserDetails",
        "responses": {
          "200": {
            "description": "Ok",
            "schema": {
              "$ref": "#/definitions/profile"
            }
          }
        },
        "security": [
          {
            "oauth2": ["r_liteprofile"]
          }
        ]
      }
    },
    "/ugcPosts": {
      "parameters": [
        {
          "$ref": "#/parameters/LinkedInHeader"
        }
      ],
      "post": {
        "summary": "Share Content",
        "description": "Share Content",
        "parameters": [
          {
            "in": "body",
            "name": "parameters",
            "schema": {
              "$ref": "#/definitions/textBody"
            },
            "required": true
          }
        ],
        "responses": {
          "201": {
            "description": "Created",
            "schema": {
              "$ref": "#/definitions/profile"
            }
          },
          "default": {
            "description": "Operation Failed"
          }
        },
        "security": [
          {
            "oauth2": ["w_member_social"]
          }
        ]
      }
    }
  },
  "parameters": {
    "LinkedInHeader": {
      "name": "X-Restli-Protocol-Version",
      "type": "string",
      "in": "header",
      "default": "2.0.0",
      "x-ntx-visibility": "internal"
    },
    "JsonQueryHeader": {
      "name": "format",
      "type": "string",
      "in": "query",
      "default": "json",
      "x-ntx-visibility": "internal"
    }
  },
  "definitions": {
    "profile": {
      "type": "object",
      "additionalProperties": false,
      "x-ntx-summary": "",
      "properties": {
        "id": {
          "type": "string",
          "x-ntx-summary": "Id",
          "description": "Profile ID or URN"
        },
        "firstName": {
          "type": "string",
          "x-ntx-summary": "First Name"
        },
        "lastName": {
          "type": "string",
          "x-ntx-summary": "Last Name"
        }
      }
    },
    "textBody": {
      "type": "object",
      "additionalProperties": false,
      "x-ntx-summary": "",
      "properties": {
        "author": {
          "type": "string",
          "x-ntx-summary": "Author"
        },
        "lifecycleState": {
          "type": "string",
          "default": "PUBLISHED",
          "x-ntx-summary": "Lifecycle State",
          "enum": ["PUBLISHED", "DRAFT"]
        },
        "specificContent": {
          "type": "object",
          "additionalProperties": false,
          "x-ntx-summary": "",
          "properties": {
            "com.linkedin.ugc.ShareContent": {
              "type": "object",
              "additionalProperties": false,
              "x-ntx-summary": "Post Contents",
              "properties": {
                "shareCommentary": {
                  "type": "object",
                  "additionalProperties": false,
                  "x-ntx-summary": "",
                  "properties": {
                    "text": {
                      "type": "string",
                      "x-ntx-summary": "Your Content Text"
                    }
                  }
                },
                "shareMediaCategory": {
                  "x-ntx-summary": "Media Category",
                  "type": "string",
                  "enum": ["NONE", "ARTICLE", "IMAGE"]
                },
                "media": {
                  "x-ntx-summary": "Media Object",
                  "type": "array",
                  "items": {
                    "$ref": "#/definitions/media"
                  }
                }
              }
            }
          }
        },
        "visibility": {
          "type": "object",
          "additionalProperties": false,
          "x-ntx-summary": "",
          "properties": {
            "com.linkedin.ugc.MemberNetworkVisibility": {
              "x-ntx-summary": "Network Visibility",
              "type": "string",
              "enum": ["PUBLIC", "CONNECTIONS"]
            }
          }
        }
      }
    },
    "media": {
      "type": "object",
      "additionalProperties": false,
      "x-ntx-summary": "",
      "properties": {
        "status": {
          "x-ntx-summary": "Publish Status",
          "type": "string",
          "default": "READY"
        },
        "description": {
          "type": "object",
          "additionalProperties": false,
          "x-ntx-summary": "",
          "properties": {
            "text": {
              "type": "string",
              "x-ntx-summary": "Media Description"
            }
          }
        },
        "originalUrl": {
          "type": "string",
          "x-ntx-summary": "Media URL"
        },
        "title": {
          "type": "object",
          "additionalProperties": false,
          "x-ntx-summary": "",
          "properties": {
            "text": {
              "type": "string",
              "x-ntx-summary": "Media Title"
            }
          }
        }
      }
    }
  },
  "securityDefinitions": {
    "oauth2": {
      "type": "oauth2",
      "flow": "accessCode",
      "authorizationUrl": "https://www.linkedin.com/oauth/v2/authorization",
      "tokenUrl": "https://www.linkedin.com/oauth/v2/accessToken",
      "scopes": {
        "w_member_social": "Post and Share on LinkedIn",
        "r_liteprofile": "Read and Write to all shared users' calendars"
      }
    }
  }
}

Limitations and points to note

Complex object support is still in Advanced Preview. Read the following limitations and points to note:

  • The x-ntx-render-version property affects the whole OpenAPI Specification. You can't select complex object support per action.
  • Actions configured prior to an Xtensionusing "x-ntx-render-version": 2 will continue to render as they did previously. New actions configured with this feature enabled will be automatically updated if there are updates to the Xtension, including breaking changes if present in the OpenAPI Specification.
  • Array parameters are set item-by-item; you can't assign a collection variable to an array parameter.
  • The default property cannot be used to define initial values in object parameters. To define initial values in object parameters, use the x-ntx-initial specification extension. See x-ntx-initial.

  • The x-ntx-summary, title, or name property defines the text for the label.

    • The x-ntx-subtext property will set the text for the subtext..

    • The x-ntx-sublabel property sets the text for the sublabel.
      If x-ntx-sublabel is not provided, the description property will set the sublabel.
    • The x-ntx-placeholder property sets the text for the placeholder
      • 
    "x-ntx-summary": "Summary",
          "x-ntx-sublabel": "Sublabel",
          "x-ntx-placeholder": "Placeholder",
          "x-ntx-subtext": "Subtext"

  • Fields are no longer ordered alphabetically. Instead, the order of fields correspond to the order that is defined in the OpenAPI Specification.
  • Some inputs do not yet support the [[ type ahead feature.