Nested Variables

InsightConnect steps ingest and produce variables that can be strings, integers, booleans, arrays, or objects. Arrays and objects can contain other variables within them, for example, an array of strings.

Nested variables create ‘levels’ of data to better organize, extract, and interact with workflow data. Many InsightConnect plugins automatically create nested variables for some data, but you can also create nested variables when you build triggers or edit output schema.

Arrays

An array is a list of items separated by commas and enclosed by square brackets. Items in the array can be of any data type that you specify.

Array of Arrays

An array of arrays typically contain arrays of the same data types, although arrays of arrays can contain different types of sub-arrays. For example, the parent array could contain an array of strings, then an array of integers, then an array of booleans like [[“hello”, “hi”, “hiya”], [3,4,5], [true, false, false]]. We recommend creating arrays of arrays with consistent data types for easier parsing.

Every array must be enclosed by square brackets, including the nested arrays.

You can access data from nested arrays with:

• Loop steps
• Input templates for artifacts
• Array indices (limited functionality)

Consider a sample array of arrays created by an API trigger: [APITrigger].[VariableName]. Each subarray contains three integers, like: [[0,1,2], [3,4,5], [6,7,8]]

Extract Array of Array Data with Loops

To extract individual integers from this array of arrays with loop steps, you can create two loops. For this example’s purposes, the first loop in the workflow is FirstLoop and the second, nested within the first, is InnerLoop. The first loop iterates over [APITrigger].[VariableName], then the inner loop iterates over the variable created by the first loop, [FirstLoop].[$item]. [FirstLoop].[$item] refers to the current nested array -- for the first iteration of the parent loop, this is the first array, [0, 1, 2]. The second, inner loop extracts these individual integers 0, 1, and 2 from the array. To reference the current iteration (integer) of the inner loop, you again use the $item variable, this time [InnerLoop].[$item].

The output of a workflow using these loops would print one artifact per integer, incrementing the number each time.

The nested loop architecture parallels the nested array data structure.

Extract Array of Array Data with Indices

You can alternatively extract nested array data with the index numbers for each level of the array. This method isn’t recommended for large data sets that constantly reshuffle or resize the data, but if you have fixed arrays and only need data from certain locations in a nested array, you can use this method.

To extract a nested array’s data at a specific index location, you need both the subarray’s index location within the parent array as well as the index location of the item within the subarray. For this example, [Trigger].[ArrayOfArrays].[0].[1] retrieves the integer 1, and [Trigger].[ArrayOfArrays].[2].[1] retrieves the integer 7.

Objects

Many InsightConnect plugins use object variables, which aggregate multiple pieces of data into one parent variable. The object cannot be broken into its individual components, but you can extract the information from each component as sub-variables.

Consider an object named [StepName].[ObjectVariable] with the contents:

 
1
{ "address": "1.2.3.4", "port": 22, “domain”: “something.com” }

This object contains three items: an IP address string, an integer port number, and a domain name string.

The variable reference [StepName].[ObjectVariable] retrieves the entire object, but not any of the three nested items. You can extract the items by key name: [StepName].[ObjectVariable].[address] to return 1.2.3.4, for example.

Create Objects with the InsightConnect UI

If you build a trigger that takes in an object as input, you can build the object key-by-key in the trigger configuration panel.

To build an object with the InsightConnect UI:

1. Create a new workflow with an API trigger.
2. In the trigger configuration panel, give the trigger a name and optional description.
3. Choose Object for the variable type of the input variable, and give the variable a name.
4. Sub-fields for the object items will appear. Configure the variable as usual by selecting a variable type and providing a name.
5. To add more items to your object, click on the nested Add Variable button. This button is located within the grey border of the current object variable you’re editing.
6. Configure any additional object items as needed.
7. Configure any additional variables, aside from the object, as needed.
8. Click Continue and configure your workflow as desired.

Use Input Templates to Extract Nested Data for Artifacts

If you want to display data from nested variables in an artifact, you can use input templates to directly access content without extra workflow steps.

Learn how to use input templates to display array or JSON object content.