Nested Array Operator

Overview

The Nested Array operator works a lot like the Create Field operator. With the Nested Array operator, you can:

• Dynamically add key/value pairs to a nested array.

• Add key/value pairs with values based on the value of another field in the nested array. For example, creating a field with a value calculated using the value from another field.

• Add key/value pairs with a conditional value. For example, adding one of 2 possible values, based on a conditional if/then expression.

• Conditionally update existing fields in a nested table.

If you know how to use the Create Field operator, you already know how to use the Nested Array operator. You can use both operators to add or update rows of a table. You can also use both to update a single row of a table or all of them. There's really only one difference between these operators. To make changes to a Data Table, you'd use the Create Field operator. If you want to make changes to a nested table, you'll use the Nested Array operator.

You can think of a nested table as a table inside a table. These can help organize large amounts of table values. In this article, you'll learn how to use the Nested Array operator to update a single row of a nested table.

You'll find the Nested Array operator under the Table group to the left of your canvas.

What You'll Learn

In this article, you'll learn:

• About the Nested Array operator's settings.

• How to add and configure a Nested Array operator.

• How to modify a Nested Array operator.

• How to copy a Nested Array operator.

• How to remove a Nested Array operator.

About the Info Window

Here's what the Nested Array operator looks like, along with its Info window:

And here's a breakdown of each setting in the Info window:

Setting	Description
Category	Grayed out and non-adjustable setting indicating the operation type.
Label	Sets the label for your operator. The label you enter here shows beneath your operator on your Data Workflow canvas. This field is optional, but set a label if you use more than one of the same operator type. A label helps you identify your operators without opening any Info windows.
Do Not Sanitize Formula	When this checkbox is clear, the operator does its best to clean up values coming into or defined in the operator. For example, removing special characters. Some of those special characters include ', $, #, &amp. The operator also cleans up complex values. For example, logically breaking up strings of numbers and letters using underscores. A sample module ID can go from "5f6b4cdfabf886024d4de2d3" to "5f_6b_4cdfabf_886024d_4de_2d_3".Sanitizing improves performance. But, it can also lead to unexpected data behavior. If your Create Field isn't behaving as expected, try selecting this box.When selected, the operator uses your values and expressions as-is. This is best when working with complex values or values that should remain unchanged.By default, this setting is selected, which means the operator doesn't attempt to sanitize.
Table Path	This is the reference key of the data you want to nest. An example would be the heading of a column in a Data Table.
Field 1-4	Notice how the Nested Array operator has 4 different Field options. This means you can add multiple fields using a single operator. Define the field you want to create or update, using the following format: key=value. For string values, add single or double quotes around the value. For example, employed="yes". The value part of the key=value expression can also include calculations, conditional expressions, and references to other fields. It can also reference values coming into the argument port, using the alias _arg. For example, this expression that uses a calculation: incomeMonthly=_arg/12. The calculation happens on the input coming into the operator's argument port. Or this one, that includes a conditional expression, a reference to another field, and a calculation: lowIncome=IF(incomeAnnual<24000,"yes","no"). Conditional expressions should use the following format: key=IF(condition,valueIfTrue,valueIfFalse).

Adding a Nested Array Operator

In this example, you'll use the Nested Array operator to update a single row of a nested table. You'll create a nested table by inputting 2 Data Tables into a Set operator, and then outputting the new table into a second Data Workflow. In this second Data Workflow, you'll use a Nested Array operator to update a patient's address information.

Here's how the completed use case will look in the Module Builder:

Here's how the completed use case will work in Express View, including a peek at the DevTools Console:

What You’ll Need

To set up this use case, you’ll need:

• 2 Data Table components

• 2 Hidden components

• 2 Data Workflow components

• 1 Button component

To set up the first Data Workflow, you’ll need:

• 2 Input operators

• 1 Set operator

• 2 Output operators

• 1 Console operator

To set up the second Data Workflow, you’ll need:

• 1 Input operator

• 1 Nested Array operator

• 1 Output operator

• 1 Console operator

NOTE  These instructions assume you have a module open, saved, and with a title.

Configure the First Data Table Component

First, you'll set up a Data Table with a customer's name and account information. Let's call this first Data Table your "top level" data. The next Data Table will be your nested table.

1.

In the Module Builder, drag and drop a Data Table component onto your canvas.

2.

Enter dtTopLevel in the Label and Property Name fields.

3.

In the data table, enter the following:

4.

Click Save.

Configure the Second Data Table Component

Now, you'll set up a nested Data Table holding the customer's current address.

1.

Drag and drop a Data Table component onto your canvas, placing it below your other Data Table.

2.

Enter dtNested in the Label and Property Name fields.

3.

In the data table, enter the following:

4.

Click Save.

Configure the First Hidden Component

In this Hidden component, you'll store the output of your first Data Workflow. The output refereences your combined tables.

1.

Drag and drop a Hidden component onto your canvas, placing it below your Data Tables.

2.

Enter array in the Property ID and Canvas Label Text fields.

3.

Click Save.

Configure the First Data Workflow Component

You'll now set up a Data Workflow to input your Data Tables and nest them into an array. The simplest way to create this array is with a Set operator. You'll also configure this first Data Workflow to trigger your second Data Workflow.

1.

Drag and drop a Data Workflow component onto your canvas. Place your Data Workflow below your Hidden component.

2.

Enter dwfSetArray in the Canvas Label Text and Property Name fields.

Configure the First Input Operator

1.

Drag and drop an Input operator onto your Data Workflow canvas.

2.

Configure the Input operator's Info window as follows:

Configure the Second Input Operator

1.

Drag and drop another Input operator onto your Data Workflow canvas.

2.

Configure the Input operator's Info window as follows:

Configure the Set Operator

1.

Drag and drop a Set operator onto your Data Workflow canvas.

2.

Configure the Set operator's Info window as follows:

3.

Connect the output port (right) of the dtTopLevel Input operator to the input port (left) of the Set operator.

4.

Connect the output port (right) of the dtNested Input operator to the input port (left) of the Set operator.

Configure the First Output Operator

1.

Drag and drop an Output operator onto your Data Workflow canvas.

2.

Configure the Output operator's Info window as follows:

3.

Connect the output port (right) of the Set operator to the input port (left) of the array Output operator.

Configure the Second Output Operator

1.

Drag and drop another Output operator onto your Data Workflow canvas.

2.

Configure the Output operator's Info window as follows:

3.

Connect the output port (right) of the Set operator to the input port (left) of the dwfNestedArray Output operator.

Configure the Console Operator

1.

Drag and drop another Console operator onto your Data Workflow canvas.

2.

Configure the Console operator's Info window as follows:

3.

Connect the output port (right) of the Set operator to the input port (left) of the Console operator.

4.

Click Save.

Configure the Button Component

To trigger your first Data Workflow, you'll add a Button component.

1.

Drag and drop a Button component onto your canvas. Place your Button component below your Data Workflow component.

2.

Enter btnUpdateAddress in the Property ID field.

3.

Enter Update Address in the Label Text field.

4.

Select Event as the Action Type.

5.

Enter dwfSetArray in the Trigger on Click field.

6.

Click Save.

Configure the Second Hidden Component

In the second Hidden component, you'll store the output of your second Data Workflow.

1.

Drag and drop a Hidden component onto your canvas, placing it below your Data Tables.

2.

Enter arrayAfter in the Property ID and Canvas Label Text fields.

3.

Click Save.

Configure the Second Data Workflow Component

You'll now input your first Data Workflow into your second Data Workflow. Then, you'll use a Nested Array operator to update the address in your nested table.

1.

Drag and drop a Data Workflow component onto your canvas. Place your Data Workflow below the afterArray Hidden component.

2.

Enter dwfNestedArray in the Canvas Label Text and Property Name fields.

Configure the Input Operator

1.

Drag and drop an Input operator onto your Data Workflow canvas.

2.

Configure the Input operator's Info window as follows:

Configure the Nested Array Operator

1.

Drag and drop a Nested Array operator onto your Data Workflow canvas.

2.

Configure the Nested Array operator's Info window as follows:

3.

Connect the output port (right) of the Input operator to the input port (left) of the Nested Array operator.

Configure the Output Operator

1.

Drag and drop an Output operator onto your Data Workflow canvas.

2.

Configure the Output operator's Info window as follows:

3.

Connect the output port (right) of the Nested Array operator to the input port (left) of the Output operator.

Configure the Console Operator

1.

Drag and drop another Console operator onto your Data Workflow canvas.

2.

Configure the Console operator's Info window as follows:

3.

Connect the output port (right) of the Nested Array operator to the input port (left) of the Console operator.

4.

Click Save.

5.

Save your module.

Preview your module in Express View, and open the DevTools Console. Click your Update Address button, and expand each Console. When you expand address, you'll see that your customer's address updated from "100 Main Street" to "200 Wall Street".

Changing a Nested Array Operator’s Settings

You can revisit and make changes to this operator.

1.

Click the Data Workflow component.

A 5-button toolbar displays above the component on hover-over.

2.

Click the (Settings) button to open the Data Workflow canvas.

3.

Click the operator to open its Info Window.

4.

Make changes to the operator's settings as needed.

5.

Click Save.

6.

Save your module.

Copying a Nested Array Operator

You can make a copy of your operator using familiar keyboard settings. You can copy and paste an exact copy of your operator, matching all settings.

1.

Hover over the Data Workflow component.

A 5-button toolbar displays above the component on hover-over.

2.

Click the (Settings) button to open the Data Workflow canvas.

3.

Click the operator you want to duplicate.

4.

On your keyboard, press Command + C (Mac OS) or Ctrl + C (Windows/Linux) to copy the operator.

5.

On your keyboard, press Command + V (Mac OS) or Ctrl + V (Windows/Linux) to paste the copied operator(s) to the Data Workflow canvas.

6.

Click Save.

7.

Save your module.

TIP  Did you know you can copy an operator and paste it into a different Data Workflow? You'll use the same steps outlined above.

Removing a Nested Array Operator

Lastly, you can delete this operator from your Data Workflow canvas. You can also use these same steps to delete a connection between two operators.

1.

Hover over the Data Workflow component.

A 5-button toolbar displays above the component on hover-over.

2.

Click the (Settings) button to open the Data Workflow canvas.

3.

Click the operator you want to delete.

4.

On your keyboard, press Delete.

5.

Click Save.

6.

Save your module.

Lab

You can view this complete use case here: https://training.unqork.io/#/form/605a1b5d50bd5c2b0f1f7d7e/edit.