Send arrays or complex objects

Some APIsA programming interface that defines how software can be interacted with by other software. require parametersA 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 Workflow Cloud. You can send arrays or complex objects by configuring your OpenAPI SpecificationA standard, language-agnostic description of RESTful APIs that can be read by both humans and machines. Formerly known as Swagger. to use the complex object renderer.

Note: It is not possible to enable complex object support on a per-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. basis. Complex objects are enabled for the whole XtensionA set of instructions for the Nintex Workflow Platform to use third-party API functionality with Nintex workflows. An Xtension may include workflow actions, start events, forms or file control.. Currently, Nintex Workflow Cloud does not offer file support with complex objects.

Working with objects

When an OpenAPI Specification uses the complex object renderer, Nintex Workflow Cloud displays the action configurationsA 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.

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

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

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.
  • Array parameters are set item-by-item; you can't assign a collection variable to an array parameter.
  • Actions configured prior to an Xtension using "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.

  • 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.
  • Earlier versions allowed a parameter to define an initial value using the parameter's default property. However, the OpenAPI Specification defines the default property as the value to use when no value is given, which should not be used for required parameters. x-ntx-render-version reflects this understanding of the default property. To set an initial value when using "x-ntx-render-version" : 2, use the x-ntx-initial property. For example, "x-ntx-initial": "My value".