Merging

This group combines data from JSON documents you have already loaded and produces a new loaded JSON document with the result. You can merge two objects into one, copy selected fields from one object into another, stack the lists from several documents into a single list, or join two lists together by a shared key — the SQL-style join.

Prerequisite: the documents you want to combine must already be loaded — created with Create JSON file or opened with an Opening instruction (or produced by an earlier JSON instruction). Merge objects and Add fields from object work on JSON objects; Combine arrays and Join arrays by key work on lists.

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

• They combine loaded documents into a new one. Each instruction reads one or more documents that are already loaded (named by their document keys) and builds a new loaded document from them. The source documents are left unchanged.
• Document keys name loaded documents. Base / Source / Left / Right / Target document key point at documents loaded in earlier steps. A key that is empty — or whose document isn’t the shape the instruction needs (an object where a list is expected, or the reverse) — counts as missing, and the instruction reacts as described in each card.
• Where the result goes (Document key, Name, Path): Document key names the new combined document so later steps can target it; leave it empty and the result becomes the current document. Name and Path set where that document will be written when you save it later, and are independent of the source documents. If you set Document key to the same key as the target/base document, the result replaces that document in place.
• Dynamic values @name: every text field — the document keys, Field names, On duplicate, Array field name(s), Key field(s), Name, Path — accepts a saved value: type @ followed by its name and the engine substitutes it at run time.
• Objects vs lists. A JSON object is a set of name → value pairs; a list (array) is an ordered series of elements. Combine arrays and Join arrays by key accept either a document that is a list, or an object that contains a list under a named field (the Array field name).
• Nothing is written to disk here. The combined result is loaded into the workflow; a later save instruction writes it out.

• Add Fields From Object .json
• Combine Arrays .json
• Join Arrays By Key .json
• Merge Objects .json

Add Fields From Object .json

Copies fields from a source object into a target object and loads the enriched result as a new document.

When to use it: to enrich one record with a few fields taken from another — for example, adding email and phone from a contacts object onto a user object.

Parameter	Meaning	Default	Required
Target document key	The loaded object that receives the fields. Empty = current document (accepts @name)	(empty)	Yes
Source document key	The loaded object the fields are taken from (accepts @name)	(empty)	Yes
Field names	Comma-separated list of field names to copy — used only when Copy all fields is off (accepts @name)	(empty)	No
Copy all fields	If yes, copies every field from the source instead of a chosen list	No	No
Copy all fields (from variable)	Reads the yes/no value from a saved value	(empty)	No
Name	File name the new document will be saved under (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Path	Folder the new document will be saved to (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Document key	Names the new document so later instructions can target it. Empty = current document (accepts @name)	(empty)	No

Important behavior: both the target and the source must be loaded objects; if either is missing or isn’t an object, nothing happens. A field is copied only if the target doesn’t already have it — existing target values are never overwritten. With Copy all fields off and Field names empty, nothing happens. Field names not found in the source are skipped. To enrich a document in place, set Document key to the same key as Target document key.

---

Combine Arrays .json

Stacks the lists from several loaded documents into a single list and loads it as a new document.

When to use it: to gather records that arrived in separate documents — for example three monthly lists — into one combined list for sorting, filtering or export.

Parameter	Meaning	Default	Required
Source document keys	Comma-separated list of the loaded documents to combine (accepts @name)	(empty)	Yes
Array field name	When a source document is an object, the name of the list field inside it to take (accepts @name)	items	No
Name	File name the new document will be saved under (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Path	Folder the new document will be saved to (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Document key	Names the new document so later instructions can target it. Empty = current document (accepts @name)	(empty)	No

Important behavior: if Source document keys is empty, nothing happens. Each key is read in turn: if its document is a list, that list is used; if its document is an object, the list under Array field name is used; anything else (missing document, no such field, the field isn’t a list) is skipped. If Array field name is empty, items is used. The elements are copied in the order the keys are listed. The result — even if empty — is loaded as the new document.

---

Join Arrays By Key .json

Joins two lists on a shared key field, in the style of a SQL join: each left element is matched to a right element with the same key value, and their fields are combined.

When to use it: to enrich one list with details from another — for example matching an orders list to a customers list by customerId so each order also carries the customer’s fields.

Parameter	Meaning	Default	Required
Left document key	The loaded document holding the left list (accepts @name)	(empty)	Yes
Left array field	When the left document is an object, the name of its list field (accepts @name)	items	No
Left key field	The field on each left element whose value is matched (accepts @name)	id	No
Right document key	The loaded document holding the right list (accepts @name)	(empty)	No
Right array field	When the right document is an object, the name of its list field (accepts @name)	items	No
Right key field	The field on each right element whose value is matched (accepts @name)	id	No
Include unmatched	If yes, left elements with no match are still kept in the result	No	No
Include unmatched (from variable)	Reads the yes/no value from a saved value	(empty)	No
Name	File name the new document will be saved under (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Path	Folder the new document will be saved to (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Document key	Names the new document so later instructions can target it. Empty = current document (accepts @name)	(empty)	No

Important behavior: the left list drives the result — if the left list can’t be found, nothing happens. Each left element is matched to a right element that has the same Left key field / Right key field value (matching ignores upper/lower case). On a match, the right element’s fields are added to the left element, but fields already on the left win (they are not overwritten). A left element with no match is kept only when Include unmatched is on — otherwise it is dropped. If several right elements share a key value, the first one is used. Right elements that aren’t objects, or whose key value is empty, are ignored. Empty array field / key field boxes fall back to items and id. The result is loaded as the new document.

---

Merge Objects .json

Merges two JSON objects into one, letting you choose what happens when the same field name appears in both, and loads the result as a new document.

When to use it: to overlay one object on another — for example applying an object of override settings on top of a defaults object.

Parameter	Meaning	Default	Required
Base document key	The loaded base object (accepts @name)	(empty)	No
Source document key	The loaded object merged on top of the base (accepts @name)	(empty)	No
On duplicate	What to do when a field exists in both: keep-original, overwrite, or keep-both	keep-original	No
Merge arrays	If yes, list fields present in both are combined into one list instead of following the On duplicate rule	No	No
Merge arrays (from variable)	Reads the yes/no value from a saved value	(empty)	No
Name	File name the new document will be saved under (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Path	Folder the new document will be saved to (accepts @name); needed to save the document — this instruction has no source file to take a destination from	(empty)	Yes
Document key	Names the new document so later instructions can target it. Empty = current document (accepts @name)	(empty)	No

Important behavior: if both objects are missing (empty key, or not an object), nothing happens; if only one is present, the result is a copy of that one. When both are present the result starts as a copy of the base, then each source field is applied by On duplicate: keep-original (the default) keeps the base’s value and drops the source’s; overwrite replaces it with the source’s; keep-both adds the source’s value under a new name (field_2, field_3, … ). Fields only in the source are always added. An empty On duplicate box is treated as keep-original. With Merge arrays on, list fields that appear in both objects are combined into a single list with exact duplicates removed (this applies on top of the field-by-field step). The result is loaded as the new document.

---