Escribal
Back to Docs

JSON

Reading values

This group reads values out of a loaded JSON document without changing it. Each instruction reaches into the data — following a path to a field, picking an element out of a list, listing a document’s field names, reporting a field’s type, or checking whether a field exists — and saves the answer for later steps to use.

Prerequisite: a JSON document must already be loaded — created with Create JSON file or opened with one of the Opening instructions (for example Open JSON File). These instructions only read; they never create a document.

These concepts recur across the instructions in this group; they are explained here once.

  • This group only reads. Nothing in the document is changed. The Save … field is the way to capture the answer — if you leave it empty, the instruction runs but the result is discarded. Save it under a name and later steps can use it with @name.
  • Document: the Document key names the loaded document to read from. If you leave it empty, the current document is used. It also accepts @name.
  • Paths (Field path): a path points at a value inside the document by naming each step separated by dots — for example person.address.city. A number as a step means a position in a list, counted from 1 — so books.1.title is the title of the first book. If any step along the path is missing, the instruction does nothing.
  • Lists (Array field name): the array instructions work on a list. Name the field that holds it (for example items), or leave Array field name empty when the document itself is already a list.
  • Dynamic values @name: the text fields — Document key, Field path, Array field name, Path prefix and Field name — accept a saved value: type @ followed by its name and the engine substitutes the value at run time. The Save … and Position fields are plain values.

Check Field Exists .json

Checks whether a field exists at a path and saves a yes/no answer.

When to use it: to let a later step react to a value being present or absent — for example only write a shipping section when order.address exists.

Parameter Meaning Default Required
Document key The loaded document to read. Empty = current document (accepts @name) (empty) No
Field path The dot-separated path to check, e.g. person.address.city (accepts @name) (empty) Yes
Save result key Saves the yes/no answer (empty or not) under this name (empty) No

Important behavior: if Field path is empty, or no document is loaded, nothing happens and nothing is saved. The path is followed up to its last step, then the existence of that last field (or list position) is tested — so a value that is present but null still counts as existing (yes). If any earlier step of the path is missing, the answer saved is no.

Iterate Array .json

Saves a list so a later For each step can loop over it. Takes either the document itself (when it is a list) or a named list field inside it.

When to use it: to prepare a list for repetition — for example load the orders list, then loop over each order to add a row.

Parameter Meaning Default Required
Document key The loaded document to read. Empty = current document (accepts @name) (empty) No
Array field name The field holding the list; empty = the document itself is the list (accepts @name) (empty) No
Save key Saves the list under this name for For each to use (empty) No

Important behavior: if the named field is missing or isn’t a list — or, when the field is left empty, the document itself isn’t a list — nothing happens and nothing is saved. If no document is loaded, nothing happens.

Iterate Fields .json

Saves every field of the document as a name/value list so a later For each step can loop over the pairs.

When to use it: to walk through an object whose field names you don’t know ahead of time — for example turn each setting into a labeled row.

Parameter Meaning Default Required
Document key The loaded document to read. Empty = current document (accepts @name) (empty) No
Save key Saves the list of {name, value} pairs under this name (empty) No

Important behavior: the document must be an object; if it is a list, or no document is loaded, nothing happens and nothing is saved. Each entry in the saved list carries the field’s name and a copy of its value.

Read All Field Names .json

Saves the names of all the document’s fields as a list.

When to use it: to get just the labels of an object — for example list every column name found in a record.

Parameter Meaning Default Required
Document key The loaded document to read. Empty = current document (accepts @name) (empty) No
Save key Saves the list of field names under this name (empty) No

Important behavior: the document must be an object; if it is a list, or no document is loaded, nothing happens and nothing is saved.

Read Array Element .json

Reads one element from a list by its position and saves it.

When to use it: to grab a single item — for example the first result, or the third row.

Parameter Meaning Default Required
Document key The loaded document to read. Empty = current document (accepts @name) (empty) No
Array field name The field holding the list; empty = the document itself is the list (accepts @name) (empty) No
Position Which element to read, counting from 1 (1 = first) 1 No
Position key (from variable) Reads the position from this variable instead of the box above (empty) No
Save key Saves the element under this name (empty) No

Important behavior: Position counts from 1 (not 0). Position key is what lets this instruction walk a list inside a Repeat for each: the loop publishes the round number in its Index key (1 for the first round), and putting that name here reads a different element each time round. If the position is below 1 or past the end of the list, nothing is saved. If the named field is missing or isn’t a list — or, with the field empty, the document isn’t a list — nothing happens. If no document is loaded, nothing happens.

Read Field Type .json

Reports the data type of a value at a path and saves it as a word.

When to use it: to branch on the shape of the data — for example handle a field differently when it holds a list versus a single value.

Parameter Meaning Default Required
Document key The loaded document to read. Empty = current document (accepts @name) (empty) No
Field path The dot-separated path to the value, e.g. person.age (accepts @name) (empty) Yes
Save key Saves the type name under this name (empty) No

Important behavior: the saved word is one of Text, Number, Boolean, Array, Object, Null, or Unknown. If Field path is empty, no document is loaded, or the path leads nowhere, nothing happens and nothing is saved.

Read Field With Dynamic Path .json

Reads a field whose path is built at run time from two parts — a prefix and a field name — and saves the value. Because both parts accept @name, the location to read can be decided by earlier steps.

When to use it: to read a field chosen while the workflow runs — for example a prefix of user plus a field name held in @chosenField.

Parameter Meaning Default Required
Document key The loaded document to read. Empty = current document (accepts @name) (empty) No
Path prefix The leading part of the path, e.g. person.address; empty = use just the field name (accepts @name) (empty) No
Field name The final field to read (accepts @name) (empty) Yes
Save key Saves the value under this name (empty) No

Important behavior: the prefix and field are joined with a dot to form the full path (or just the field name when the prefix is empty). If Field name is empty, no document is loaded, or the path leads nowhere, nothing happens and nothing is saved.

Read Nested Field .json

Reads a value at a path and saves it.

When to use it: to pull out one buried value — for example the city from person.address.city.

Parameter Meaning Default Required
Document key The loaded document to read. Empty = current document (accepts @name) (empty) No
Field path The dot-separated path to the value, e.g. person.address.city (accepts @name) (empty) Yes
Save key Saves the value under this name (empty) No

Important behavior: a number as a path step selects a list position counted from 1 (e.g. books.1.title is the first book). If Field path is empty, no document is loaded, or any step of the path is missing, nothing happens and nothing is saved.

This documentation is the help of the application, and it comes underCreative Commons Attribution 4.0.