Build JSON

The Build JSON action assembles a JSON object and stores it in a temporary variable. It can either append that object to a JSON array, turning a list of Records or line items into an array of objects, or write it out as a single object on its own. The usual reason to build JSON is to send it somewhere, so the result is normally passed to a REST Call action, but it can be used anywhere a structured JSON value is needed.

Because the action builds the JSON properly rather than gluing text together, values containing quotes, backslashes or other awkward characters are handled for you and cannot break the result.

Options

• Temp Variable Name - The name of the temporary variable that holds the result. The red label beside the box shows the exact variable to use to read it back later, for example [DMTMP(JSONArray)].
• Output - Choose whether the action produces a JSON array or a single JSON object. Set to array, the action appends to whatever the variable already holds. Set to object, it replaces the variable's contents each time it runs.
• Object Source - Choose whether to build the object from a field mapping table or from a block of JSON text. Use the mapping table when you want to choose the properties one at a time and control their types. Use JSON text when you already have a complete object, which is most often a [JSONRECORDOBJ(...)] variable.
• Property Name - The name of the property as it will appear in the JSON. Spaces are allowed, so Invoice Number is a valid property name.
• Value - The value for that property. This can be a static value or any variable.
• Type - Controls how the value is written into the JSON. See Property Types below.
• If Empty - Select how to handle an empty value - Omit, Blank or Null.
• JSON Object - Used when the Object Source is set to JSON text. This must resolve to one complete JSON object.

Property Types

An empty value is written as null whatever the type, unless Omit if Empty is checked.

Building an array from a list of Records

Place a Build JSON action inside a Search and Run Actions action. The search finds the Records, and Build JSON runs once for each one, appending an object to the array. Afterwards the variable holds the complete array, ready to use in a REST Call or anywhere else.

Nesting line items inside each Record

Raw JSON is what makes nesting possible, and it works by pointing one Build JSON action at the result of another. Inside the loop over Records, first run a Line Item Loop containing its own Build JSON action that appends each line to a second variable, for example LineItems. Then, in the Build JSON action that builds the Record object, add a property whose Value is [DMTMP(LineItems)] and whose Type is Raw JSON. The lines are nested inside the Record object as a real array rather than as a lump of text.

Within a Line Item Loop the fields of the current line are available as [LI:FieldName], so a line's description is [LI:Description]. Note that the [JSONRECORDOBJ(...)] variable reads header fields only, so use the mapping table with [LI:...] values when building line item objects.

There is no limit to how deep this can go. Anything you can build into a temporary variable can be nested into another object as a Raw JSON property.

Clearing the variable

The action always appends and never clears the variable first. To start a fresh array, clear the variable yourself using a Multiple Temp Variables action with the value set to [DEL].

Where you put that clearing action matters. To build one array from a whole search, clear before the loop starts. To build a separate array for each Record, such as a set of line items belonging to that Record, the clearing action must be the first action inside the loop, because clearing outside the loop only resets it once and every Record after the first would inherit the previous Record's items.

Wrapping the array

Many systems expect the array to sit inside a larger object, such as {"orders":[ ... ]}. Use a Multiple Temp Variables action after the loop and set a variable to {"orders":[DMTMP(JSONArray)]} to produce that shape.