Create Field Operator

Overview

The Create Field operator is a multi-purpose operator. At the simplest level, it does what its name suggests: creates fields. But, you can also use the Create Field operator to:

• Dynamically add key/value pairs based on your end-user's input.

• Add key/value pairs with values based on the value of another field. 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 1 of 2 possible values, based on a conditional if/then expression.

• Update existing fields in a Data Table.

You'll find the Create Field operator in the Table group at the left of the Data Workflow canvas.

In this article, you'll learn the basics of how to use the Create Field operator and its settings.

What You'll Learn

In this article, you'll learn:

• About the Create Field operator's settings.

• How to add and configure the Create Field operator.

• How to modify a Create Field operator.

• How to copy a Create Field operator.

• How to remove a Create Field operator.

Info Window Settings

Here's what the Create Field operator looks like, along with its Info window:

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

Setting	Description
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.
Field 1-5	Notice how the Create Field operator has 5 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 and Configuring the Create Field Operator

Next, you'll learn how to use the Create Field operator. Here, you'll see how to add the same key/value pairs to every row in a table.

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

Here's how the completed use case works in Express View, including a peek at the final table in the DevTools Console:

What You Need

For this use case, you need:

• 1 Data Table component

• 1 Button component

• 1 Data Workflow component

For your Data Workflow, you need:

• 1 Input operator

• 1 Create Field operator

• 2 Console operators

Configure the Data Table Component

First, add a Data Table to hold your key/value pairs.

1.

Drag and drop a Data Table component onto your canvas.

2.

Enter dtTable in the Label and Property Name fields.

3.

In the data table, enter the following:

4.

Click Save.

Configure the Data Workflow Component

With the Data Table set up, you're ready to use the Create Field operator to add 2 new key/value pairs to each row.

1.

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

2.

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

Configure the Input Operator

Start by connecting your Data Table to the Data Workflow using an Input operator.

1.

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

2.

Configure the operator's Info window as follows:

Configure the Create Field Operator

Next, set up the Create Field operator. This operator adds 2 new key/value pairs to each row (object) of your table (array).

1.

Drag and drop a Create Field operator onto your Data Workflow canvas.

2.

Configure the operator's Info window as follows:

3.

Connect the output port (right) of the Input operator to the input port (left) of the Create Field operator.

Configure the First Console Operator

Console operators give you a look inside the action of your Data Workflow. This Console operator shows your data before adding your key/value pairs.

1.

Drag and drop a 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 Input operator to the input port (left) of this first Console operator.

Configure the Second Console Operator

This Console operator shows your data after adding your key/value pairs.

1.

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

2.

Configure Console operator's Info window as follows:

3.

Connect the output port (right) of the Create Field operator to the input port (left) of the After Create Field Console operator.

4.

Click Save.

Configure the Button Component

Finally, add a button to trigger your Data Workflow.

1.

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

2.

Enter btnRunDWF in the Property ID field.

3.

Enter Run Create Field in the Label Text field.

4.

Select Event as the Action Type.

5.

Enter dwfCreateField in the Trigger on Click field.

6.

Click Save.

7.

Save your module.

Now, test your Data Workflow. Preview your module in Express View and open the DevTools Console. Click the Run Create Field button and see what displays in the DevTools Console:

Changing a Create Field 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 Create Field 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 Create Field 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 find the completed Adding the Same Key/Value Pairs to Every Row in a Table lab here: https://training.unqork.io/#/form/5f6e280419c4e6024ed26702/edit.