Escribal
Back to Docs

JSON

Modifying

This group changes a loaded JSON document in place — adding, changing, renaming and removing fields, and adding, replacing and removing elements of a list. There is nothing to save: each edit stays in the document and is written out when the document is later saved.

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 concepts recur across the instructions in this group; they are explained here once.

  • This group edits the document. Unlike the reading instructions, these change the document directly. The change is kept and written out the next time the document is saved.
  • Document: the Document key names the loaded document to edit. If you leave it empty, the current document is used. It also accepts @name. (Copy Field and Move Field work across two documents, so they use a Source key and a Target key instead.)
  • The document must be an object — a set of named fields. If no document is loaded, or the loaded document is a bare list, the field instructions do nothing.
  • Dynamic values @name: the text fields — Document key / Source key / Target key, the field-name fields, Array field name, and the Value / New value fields — accept a saved value: type @ followed by its name and the engine substitutes the value at run time.
  • Setting a value — plain text or a saved value (from variable): the Value and New value fields set the field to that text. To store something that isn’t plain text — a number, a yes/no, a list, or a whole object — use the matching (from variable) field instead: Value key / New value key names a saved value and the instruction copies it in as-is, keeping its type, ignoring the plain-text field. Position works the same way with Position key. Leave the (from variable) fields empty to use the normal field.
  • List positions count from 1 (1 = the first element) for the element instructions.

Add Element To Array .json

Adds a value to a list held in a field — at the end, or at the start.

When to use it: to append a new item to a list — for example add an order to the orders list.

Parameter Meaning Default Required
Document key The loaded document to edit. Empty = current document (accepts @name) (empty) No
Array field name The field that holds the list, e.g. items (accepts @name) (empty) Yes
Value The text value to add (accepts @name) (empty) No
Add at start Yes = insert at the beginning; No = append at the end No No
Value key (from variable) Instead of Value, add a saved value as-is, keeping its type (empty) No
Add at start (from variable) Reads the yes/no value from a saved value (empty) No

Important behavior: the named field must already exist and be a list; otherwise nothing happens. If Array field name is empty, or no document is loaded (or it isn’t an object), nothing happens. When Value key is set it takes precedence over Value.

Add Field .json

Adds a new field with a value. Leaves the document untouched if a field with that name already exists.

When to use it: to introduce a new field — for example add a status field set to active.

Parameter Meaning Default Required
Document key The loaded document to edit. Empty = current document (accepts @name) (empty) No
Field name The name of the field to add, e.g. newField (accepts @name) (empty) Yes
Value The text value for the new field (accepts @name) (empty) No
Value key (from variable) Add a saved value as-is (number, list, object…) instead of Value (empty) No

Important behavior: if a field with that name already exists it is left untouched — use Modify Field to change an existing field. If Field name is empty, or no document is loaded (or it isn’t an object), nothing happens. When Value key is set it takes precedence over Value.

Copy Field .json

Copies a field’s value into another field, optionally in a different document. The original is left in place.

When to use it: to duplicate a value — for example copy name into displayName, or copy a field from one document into another.

Parameter Meaning Default Required
Source key The document to copy from. Empty = current document (accepts @name) (empty) No
Source field name The field to copy, e.g. name (accepts @name) (empty) Yes
Target key The document to copy into. Empty = the same document as the source (accepts @name) (empty) No
Target field name The field to write the copy to, e.g. nameCopy (accepts @name) (empty) Yes

Important behavior: the source field must exist; if it doesn’t, or either field name is empty, nothing happens. If the target field already exists it is overwritten. A copy of the value is written, so later changes to one field don’t affect the other. If Target key names a document that isn’t loaded (or isn’t an object), nothing happens.

Modify Element Field .json

Writes one field inside an element of an array, choosing the element by its position.

When to use it: to leave a result in each record while a For Each walks them — the calculated amount of an invoice line, a status, a total. Modify Field only reaches the fields at the top of the document, and Replace Element In Array swaps the whole element, so changing one field with it meant rebuilding the record.

Parameter Meaning Default Required
Document Document the instruction applies to (current document) No
Array field name Name of the array field. Empty = the document itself is the array. Supports @name (empty) No
Position Position of the element (starts at 1) 1 No
Field name Field to write inside the element. Supports @name (empty) Yes
Value Text to write. Supports @name (empty) No
Position (from variable) Reads the position from a saved value — this is where the loop’s Index goes (empty) No
Value (from variable) Reads the value from a saved variable, keeping its type (a number stays a number) (empty) No

A field the element does not have yet is added, because on the first turn the result does not exist anywhere. A position that does not exist does nothing, and neither does an element that is not an object.

Modify Field .json

Changes the value of an existing field. Does nothing if the field doesn’t exist.

When to use it: to update a value — for example change status from pending to done.

Parameter Meaning Default Required
Document key The loaded document to edit. Empty = current document (accepts @name) (empty) No
Field name The existing field to change, e.g. status (accepts @name) (empty) Yes
New value The new text value (accepts @name) (empty) No
New value key (from variable) Set the field to a saved value as-is instead of New value (empty) No

Important behavior: if the field doesn’t exist it is not created — use Add Field for that. If Field name is empty, or no document is loaded (or it isn’t an object), nothing happens. When New value key is set it takes precedence over New value.

Move Field .json

Moves a field from one document into another (or to a new name in the same document), removing the original.

When to use it: to relocate a field — for example move total out of one document and into a summary document.

Parameter Meaning Default Required
Source key The document to move from. Empty = current document (accepts @name) (empty) No
Source field name The field to move, e.g. total (accepts @name) (empty) Yes
Target key The document to move into. Empty = the same document as the source (accepts @name) (empty) No
Target field name The name to give the field at the destination; empty = keep the same name (accepts @name) (empty) No

Important behavior: the source field must exist; if it doesn’t, or Source field name is empty, nothing happens. The original field is removed after the move. If the destination already has a field with that name it is overwritten. If Target key names a document that isn’t loaded (or isn’t an object), nothing happens.

Remove Element From Array .json

Removes the element at a given position from a list.

When to use it: to drop one item from a list — for example remove the second entry.

Parameter Meaning Default Required
Document key The loaded document to edit. Empty = current document (accepts @name) (empty) No
Array field name The field that holds the list, e.g. items (accepts @name) (empty) Yes
Position Which element to remove, counting from 1 (1 = first) 1 No
Position key (from variable) Take the position from a saved value instead of Position (empty) No

Important behavior: Position counts from 1. If it is below 1 or past the end of the list, nothing happens. The named field must exist and be a list; otherwise nothing happens. If Array field name is empty, or no document is loaded, nothing happens.

Remove Field .json

Removes a field and its value from the document.

When to use it: to delete a field — for example strip an internal debug field before saving.

Parameter Meaning Default Required
Document key The loaded document to edit. Empty = current document (accepts @name) (empty) No
Field name The field to remove, e.g. debug (accepts @name) (empty) Yes

Important behavior: if the field isn’t there, nothing changes (no error). If Field name is empty, or no document is loaded (or it isn’t an object), nothing happens.

Rename Field .json

Renames a field, keeping its value.

When to use it: to fix or change a field’s name — for example rename oldName to newName.

Parameter Meaning Default Required
Document key The loaded document to edit. Empty = current document (accepts @name) (empty) No
Current name The existing field to rename, e.g. oldName (accepts @name) (empty) Yes
New name The name to give it, e.g. newName (accepts @name) (empty) Yes

Important behavior: nothing happens if the current field is missing, or if a field with the new name already exists (so an existing field is never overwritten). If either name is empty, or no document is loaded (or it isn’t an object), nothing happens.

Replace Element In Array .json

Replaces the value at a given position in a list.

When to use it: to overwrite one item — for example change the third item to a new value.

Parameter Meaning Default Required
Document key The loaded document to edit. Empty = current document (accepts @name) (empty) No
Array field name The field that holds the list, e.g. items (accepts @name) (empty) Yes
Position Which element to replace, counting from 1 (1 = first) 1 No
New value The new text value for that element (accepts @name) (empty) No
Position key (from variable) Take the position from a saved value instead of Position (empty) No
New value key (from variable) Use a saved value as-is instead of New value (empty) No

Important behavior: Position counts from 1; below 1 or past the end of the list does nothing. The named field must exist and be a list. When New value key is set it takes precedence over New value. If Array field name is empty, or no document is loaded, nothing happens.

Set Field To Null .json

Sets an existing field’s value to null — an explicit “no value”.

When to use it: to mark a field as empty or unknown while keeping the field itself — for example clear endDate but keep the field present.

Parameter Meaning Default Required
Document key The loaded document to edit. Empty = current document (accepts @name) (empty) No
Field name The existing field to clear, e.g. endDate (accepts @name) (empty) Yes

Important behavior: the field must already exist; if it doesn’t, nothing happens (it is not created). This sets the value to null, which is different from Remove Field — that deletes the field entirely. If Field name is empty, or no document is loaded (or it isn’t an object), nothing happens.

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