Use a graphical interface to work with
collections of complex structured data. Help design users understand the
organization of structured data, and add, remove, or configure its individual
elements.
Complex data allows you to encode and store structured data in a machine-readable format such
as JavaScript Object Notation (JSON) or eXtensible Markup Language (XML). You can use the Flow Designer interface to view and understand
the organization of structured data as well as create data structures. For example, you can
create a contact data structure consisting of information you look up from a user record such as
first name, last name, and email address.
You can create complex data from these Flow Designer interfaces.
Table 1. Complex data usage examples
Flow Designer interfaceExample usage
Action inputs and outputs
Create an action that generates an object from record data. Populate the object using
record data the action looks up. See Create a custom action to generate an object from a record
Script step input and output variables
Write a script to create an array of objects from a list of records. See Create a custom action to generate an array of objects from a list of records .
Write a script to parse a JSON document into an output of type Object.
Subflow inputs and outputs
Create a subflow that accepts an object as an input and uses it to call an external
service.
XML parser step
Target field configurationsParse an XML payload into a complex data object using the XML parser step.
Benefits
Complex data offers these benefits.
Parse and format data without having to write code. For example, create data variables to
parse a response message or format a request message.
Create arbitrary data structures. For example, create an issue data structure that combines
information from existing interaction and incident records, or create a data structure to
support a custom integration.
View the organization of data structures. For example, an issue data structure might
consist of a user object to describe who to contact about the issue and a history object to
describe the work done to resolve it. You could configure a notification action with the path
to the email address listed in the user object, and call an escalate issue subflow with the
path to the status or reassign count from the history object.
Allow access to data structure from API calls. For example, call an action or subflow from
a script and use the predefined data structure as input values.
Save and reuse data structures as templates. For example, save the user object as a
template data structure for reuse in other actions and flows.
Data structure
A data structure is a collection of
related data elements organized into a hierarchy. Each element in a data
structure has its own data type and its own unique position in the
hierarchy.
The Editor pane displays data structure hierarchy with indentation. The indentation level
identifies whether an element is a parent, child, or sibling in the hierarchy. Parent elements
have children indented underneath them, and siblings have the same indentation level.
Note: The
Flow Designer interface allows you to
create hierarchies with an unlimited number of child levels, but you may have to scroll
horizontally to see them.
For example, this data structure consists of an Employee parent element with four child
elements for ID Number, Name, Start Date, and Contact Email. The Contact Email element is also a
parent element with one child.
Figure 1. Sample inputs for an Employee object
The Data pane displays data structure hierarchy as a tree of collapsible and expandable data
pills just like it does with record variables. Parent elements have an arrow icon to collapse or
expand the hierarchy.
For example, here is the Employee data structure as seen from the Data pane.
Figure 2. Sample data pill for an Employee objectYou can use the Data pane or Data picker to select specific values from a data structure. Data
structures are similar to data pills for records in that you can dot-walk or navigate to
specific elements within the structure. When you select a data element, Flow Designer displays the path to it as a
data pill just like any other data element selection. For example, if you select the Start Date
data element, the path is [Input->Employee->Start Date] .
You can use an element data path the same way you can an XPath or JPath. Sometimes you may
even convert the data pill path into one of these path notations.
Complex data types
You build data structures using one or more Array or Object
variables. Only these variable data types support child variables.
An Array variable contains values for one type of item. The parent variable is always of an
Array data type, and there is always only one child variable, which is one instance of the data
type supported by the array. Create Array variables when an input or output accepts multiple
values of the same data type.
For example, you could create a Contact Email array to list all the email addresses associated
with a given person.
Table 2. Sample data structure for the Contact Email array
Component label
Data Type
Sample Data
Contact Email
Array.String
beth.anglin@example.com and beth@anglin.com
Contact Email_child0
String
An Object variable contains any number and arrangement of child variables that each have their
own data type and values. Nesting Object variables allows you to create complex data structures
similar to a table schema where one table has related records in another table. Create Object
variables when an input or output accepts one or more related properties.
For example, you can create an Employee object to define information about the people who work
at a company.
Table 3. Sample data structure for the Employee object
Component label
Data Type
Sample Data
Employee
Object
ID Number
Integer
20190304000101
Name
String
Beth Anglin
Start Date
Date/Time
March 4, 2019
Contact Email
Array.String
beth.anglin@example.com and beth@anglin.com
Only these variable data types can be parents.
Table 4. Parent data types
Data type
Description
Array.Array
A container for arrays. Adds a read-only child item of type Array.
Array.True/False
A container for true/false values. Adds a read-only child item of type
True/False.
Array.Choice
A container for choice values. Adds a read-only child item of type Choice.
Array.Date/Time
A container for date/time values. Adds a read-only child item of type
Date/Time.
Array.Integer
A container for integer values. Adds a read-only child item of type Integer.
Array.Object
A container for objects. Adds a read-only child item of type Object, which displays
the Add Child Item option.
Array.String
A container for string values. Adds a read-only child item of type String.
Object
A container for other data elements. Displays the Add Child
Item option.
Array and Object variables only support these child data types.
Array
True/False
Choice
Date/Time
Integer
Object
String
Note: The data types in array and object variables are not Glide elements. There may not be
complete compatibility between these items and Now platform types.
Advanced options
Object variables have advanced options to save and load data structures. These options allow
you to reuse a data structure defined in one location in another. For details on advanced
options see Advanced options for action inputs .
Data structure templates
Data structure templates allow you to reuse Object variables in multiple actions or subflows.
For example, you can create a data structure to parse a response and then later reuse that same
data structure to format a request. A template stores the list of child variables and their
structure within an object. Each Object variable has an Advanced Option to save it as a
template.
When you apply a template, you are creating a copy of the original structure. Any changes you
make after applying a template do not affect the template, nor do they affect other actions that
use the template.
Array data pills
Objects that contain array data may require For Each flow logic to
process. For example, a user object that contains an array of email addresses would require a
For Each flow logic loop to send a notification to each email
address.
Object data pills
You can design actions that accept object data pills as input values. For example, you might
create a notification action that accepts a user object as an input. If the user object consists
of values for first name, last name, and addresses, then the notification action has access to
all these values. To configure an action input with an object data pill, you must create an
object earlier in the flow.
Figure 3. Sample action that accepts an object data pill
You can use an object data pill or any of its child elements to configure an input. When you
configure an input value with an object data pill, Flow Designer makes any child elements of the
object read-only, and the action uses the values provided by the object. For example, you can
create a flow where one action generates a user object and another action sends a notification
to the user specified in the object.
Figure 4. Sample action configured to use an object data pill
When you configure the child elements of an object, you must manually provide data pills for
each child element of the object. For example, you can manually configure the user object with
record values from an earlier action.
Script support
Create and reference complex
data from a script. Use a script when your source data comes from a data stream,
a REST step response, or a Look Up Records step. See Script support for complex data for more information about scripting with
complex data.
Null values
When a name-value pair contains an empty or unknown value, the value is set to the null data
type. For example, here is an object constructed from an approval record. In this case, the
note has a null value.
{
"Approval Details": {
"approvalStatus": "pending_approval",
"approver": {
"approver_assignee": "Approver",
"approver_email": "approver@example.com",
"approver_firstname": "Approval",
"approver_lastname": "User",
},
"note": null,
"reasons": [
"The requester has no manager defined."
],
}
}
Design considerations
Follow these design guidelines to create reusable and maintainable data structures.
Minimize the number of child levels in the hierarchy
The more child levels a data structure has, the more difficult it is to view and select any
specific data variable from the hierarchy. While you can build data structures with any number
of child levels, it becomes difficult to navigate and understand data structures with more
than seven child levels. For the best user experience, avoid creating data structures that
have so many child levels you must scroll horizontally to see and populate them.
Create a separate object for each type of record data
Most Flow Designer data is record
data whether it is from an instance or an external system. This design method ensures that you
know what the object contains and where the data came from.
Recreate record data structures
When building objects that receive or transmit record data, review the database dictionary
entries for these records and create matching object data structures. For example, suppose
that you want an object to contain data from incident and configuration item records. You
might create a string element for the incident short description field and an array of strings
element for the configuration item class field.
Create objects to combine different types of records
If you need information from multiple types of records, create an object that contains all
the information you need. You can then use the object to format or parse data in Flow Designer .
