Building a mapping with the graph editor

At a glance

• A graph entry's mapping is a chain of connected nodes, ending at one output.
• Add a node by browsing or searching a categorized list of blocks.
• Click a node to configure it: its Options (what to fill in), its Derivations (options built from their own sub-graph), and its Template (the raw generated code).
• Undo and redo live in the graph's own header, separate from any browser or OS shortcut.
• The footer at the bottom always shows the live value the graph currently produces — or why it can't, if something's wrong.

This is the core skill in MorphMapper — building a mapping visually, node by node, for any entry you set to the Graph type in Working with entries.

A brand new graph shows a single Start Graph button in the middle of an empty canvas — click it to open the node picker for your very first node. Every graph after that opens the same picker from a "+" on the canvas or from a node's own output.

Adding a node

Open the node picker and you'll see every available block, grouped by category (things like transformations, math, logic, or table-specific operations — what's available depends on your file's type). Search narrows the list; each entry shows its name and a short description before you commit to it. Click one to add it to your graph.

Which blocks are offered depends on the file type your template is built for — a table-based template offers different blocks than an XML one, for instance, because the underlying document structures are different.

Not every block starts in a failed state the way Anchor does when empty — a Literal node, for instance, shows a plain "Output will appear after execution" message and a green success mark even before you've typed a value, since an empty literal is still a valid (empty) result.

The same holds for other Transformer blocks — a freshly added Concatenate node, for example, also starts in that same successful, unconnected state until you wire it up.

Zoom and pan controls sit in the canvas's top-right corner (zoom in/out, fit to view, and a lock to stop accidental panning) — standard canvas navigation, not specific to any one graph.

The graph's own header

A graph, once you're inside one, has its own small header, separate from the workspace's top bar:

• Back arrow — steps back out one level: from a nested derivation graph to the graph it belongs to, or from a top-level graph back to wherever you opened it from.

• Breadcrumbs — show your position when you're nested inside a graph that belongs to another graph's option (see Derivations below). They're a readout, not a control — clicking a breadcrumb does nothing; use the Back arrow to actually move up a level.

• Undo / redo — steps backward and forward through your recent changes to this graph. This is specific to the graph editor, not a general "undo everything" — it's grayed out when there's nothing to undo or redo.

• Run — re-evaluates the graph on demand.

• Settings (gear icon) — opens the same output view the footer's preview opens (see Watching the result), with a Template tab (the generated code) and an Output tab (the evaluated result) side by side.

  

Connecting nodes

A graph is a chain: nodes feed into each other, ending at one final output. Connect a node's output to the next node's input to build that chain up. Every graph you build ends at the same place — the terminal node, whose result becomes the entry's value.

Every node card also shows its own live status inline — before it's connected to anything, it shows Failed to evaluate with a reason ("Template did not return a node result"), which clears automatically once the chain reaches the terminal node correctly. You don't have to open a node to know it's not wired up yet.

Some inputs accept more than one connection at once — Concatenate or OR, for instance, or a Switch Case node's cases input. Once you've connected two or more nodes into the same input, the card grows a numbered Inputs list naming each connected source, with small up/down arrows next to each one so you can reorder which input is fed in first without having to disconnect and reconnect anything.

Configuring a node

Click a node to open its configuration panel. What you'll find there:

• Options — the fields this specific block needs filled in, using whatever input makes sense for each one (a plain text field, a dropdown, a checkbox, or a button that lets you click directly into your source file to pick a value — see Selecting values from the source file).
• Derivations — for any option whose value isn't something you type directly, but is itself built from another small graph. This tab lists those and lets you jump straight into editing them.
• Template — the actual generated code this node produces, if you want to see exactly what it's doing under the hood.

Not every block has configurable options — a node with nothing to configure opens straight to its Template view instead.

Each option also has a small type-switcher icon next to its label, for changing how that option's value is sourced: a typed-in literal, a reference to a declared variable, raw code, a boolean toggle, or a graph of its own — which of these are offered depends on the option. Switching one to Graph is what actually creates a derivation: it opens a nested graph editor for that option right away, and once you've built something there, it shows up in the node's Derivations tab so you can jump back into it later.

Which choices actually appear varies by field, confirmed live. The Literal node's own Literal field offers all five (Literal, Reference, Graph, Code, Boolean) — but Anchor's Selector field, and Replace Symbols' Global and Case Insensitive checkboxes, only ever offer three: Literal, Reference, and Graph. Code and Boolean simply don't show up as choices on those fields, even though the menu component is the same one everywhere.

• Literal — the field's own native input (a text box, number box, checkbox, or selector button, depending on the option) stays as-is. This is the default for every option.
• Reference — replaces the field with a searchable combobox titled "Select reference," listing every variable available in this context: your own declared environment variables by name, plus the template's own internal schema variables (shown with their raw lowercase names, like clientidentifierraw or selector) — each row paired with a type badge (any for most), and a footer reading "N variables available." Worked example: on an Anchor's Selector switched to Reference, picking Invoice reference from that list sets the Template tab to "$invoicereference" and the node's Output to the unresolved placeholder $invoicereference — the raw variable name, not a value, since nothing upstream feeds it one.
• Graph — opens a nested graph editor for that option right away (see Derivations below); once built, it shows up in the node's Derivations tab.
• Code — replaces the field with a plain single-line text input plus a separate Insert button (grayed out until you've typed something). Unlike every other option type, typing here doesn't apply live: the field's actual value stays whatever it was until you click Insert, at which point the button disables again, a small "Code inserted" note appears, and the node's Output updates. Worked example: switching a Literal node's Literal field to Code and typing "acme" leaves the Template tab reading "" and the Output stuck on its prior state until Insert is clicked — after that, Output reads acme.
• Boolean — replaces the field with a single checkbox labeled with the current value (False or True), defaulting to False. Unlike Code, this one does apply live: clicking it flips the Output immediately (verified: unchecked → False, checked → True) with no separate commit step.

Hovering or selecting a node's card also reveals its own small toolbar — a Replace icon (swap this node for a different block without losing its position in the graph), a Run button scoped to just that node, and a delete (trash) icon — separate from the graph-wide Run in the header above.

Watching the result

The bar at the bottom of the graph editor always shows the current status of the whole chain — idle, running, succeeded, or failed — along with a live preview of the value it currently produces. Click the preview to see the full output rather than a truncated one. If something's wrong further up the chain, this is the fastest way to notice, since the status updates as you build.

That screenshot shows the whole loop end to end: a value selected in the file view on the left, captured into the node's Selector field on the right, and the node's status flipping from failed to succeeded the moment it has something valid to work with.

Available nodes

The node picker groups every block into the categories below. Which ones actually show up for you depends on your file type, as noted above — this is the full catalog across all file types.

Core

• Anchor — select text to act as a reference point of the value you want to extract. Covered in detail above and in Selecting values from the source file. XML and JSON templates give Anchor that same single Selector field, but selecting by path instead of by text. A table-based template (Xls/csv) replaces the Selector field with a different set of options entirely: a Reference choice between Absolute and Relative cell addressing, a Column and Row number to target (with Absolute) or shift by from a reference cell (with Relative — which also adds back a Selector field, to pick that reference cell), an Iterate Rows checkbox, and a Whitespace checkbox to strip trailing whitespace from the output.

  

Literal

Adds a constant, typed-in value to your template — a string, a number, or a boolean — rather than something pulled from the source file.

• Literal — a single text field for the value itself. There's no default; an empty Literal is still a valid (empty) result, which is why a freshly added Literal node starts green instead of failed (see Adding a node above).

Worked example: with the value typed in as Acme Shipping Ref, the node's Template tab shows the generated code as "Acme Shipping Ref" (a plain JSON string literal), and its Output is Acme Shipping Ref.

Document Variables

Reads one of a small set of variables tied to the document itself, rather than a value from inside its content — useful for email- or text-based inputs where the file name, sender, or subject line is itself part of the data you want to map.

• Variable — a dropdown of the variables available for your file type. For an XML/import template the choices are Email Body, Email From, Email Subject, PDF Body, Text Body, File Name, and XLS Column; which of these actually apply depends on the template's input source (an XML file over plain File input won't have a populated email or text body at runtime, even though the option is still selectable).

Worked example: selecting File Name on an XML template's Document Variables node produces $emailData.fileName in the Template tab — the raw variable reference the generator emits, regardless of file type — since MorphMapper always exposes the same variable resolution code and lets the runtime for that particular input source fill it in.

Anchor Variable

Retrieves a field value using a variable path, selected from the file the same way an Anchor's Selector is.

• Selector — a text field, filled in via the same pick-from-file selector button as Anchor's Selector, for the variable path to retrieve. No default.

Worked example: selecting the OrderNumber value from the sample file sets Selector to $inputdocument..@, and the Template tab emits {"$getVariable": "inputdocument..@"} — the leading $ is stripped from the selector string when it's passed to $getVariable. With nothing else in context, the node's Output stays a $__reserved__result__<id> placeholder, since resolving a variable path means evaluating it against the runtime's variable table.

Transformers

Concatenate

Combines two or more incoming values into a single string. It has no Options tab of its own — instead of filling in fields, you wire two or more upstream nodes into its inputs and it joins their values in wiring order.

Worked example: added fresh with nothing wired in, the Template tab emits {"$utils.concat.selective": []} — an empty list of values to join, since nothing is wired into it yet. Each upstream node you wire in adds one more entry to that list.

Remove Words

Removes a number of words from the start and/or end of a string.

• Starting count — a number field for how many words to remove from the start of the string. Defaults to 0.
• Words — a number field for how many words to remove from the end of the string. Defaults to 0.

Worked example: added fresh with nothing wired in and Starting count set to 1 (Words left at 0), the Template tab emits {"$helpers.removeWords": [[[]], 1, 0]} — the incoming value as an (empty, since nothing is wired) list, then Starting count and Words in order.

Remove Special Characters

Strips special characters, and optionally trailing whitespace, from a string.

• Trim Whitespace — a checkbox for whether to also remove trailing whitespace from the string. Checked by default.

Worked example: added fresh with nothing wired in and Trim Whitespace left at its default (checked), the Template tab emits {"$utils.regexp.replace": [undefined, ["[\n,\r, ,/,(,)]", "g"], ""]} — a regex character class matching newlines, carriage returns, spaces, slashes, and parentheses, replaced globally with an empty string. The node's Output already resolves (even with nothing wired in) to [ [ null ] ].

Remove Leading and Trailing Spaces

Trims spaces from the start and end of a string. It has no options of its own.

Replace Symbols

Replaces one or more symbols in a string with a target value.

Field	Type	Description	Default
Replace	Tag combobox	Type a symbol (or sequence of characters) and confirm via + Create to add it as a chip; add more than one chip to replace several different symbols in the same pass.	None
With	Tag combobox	The value to replace matches with.	None
Global	Checkbox	Replace every occurrence in the string rather than only the first.	Unchecked
Case Insensitive	Checkbox	Whether the match against Replace ignores letter case.	Unchecked

Worked example: with Replace set to a single - chip, With set to a single _ chip, and Global left unchecked, the Template tab emits {"$utils.regexp.replace": [undefined, ["[-]"], "_"]} — the chip(s) in Replace become a regex character class, and (since Global is unchecked) no g flag is added as a second element of that array; checking Global adds "g" there, the same way Remove Special Characters' fixed character class does above.

Parse to Number

Parses a string to a whole number. It has no options of its own.

Parse to Float

Parses a string to a floating-point number. It has no options of its own.

Parse to Float (Alternative)

Parses a string to a floating-point number, with reversed comma-and-dot notation from the plain Parse to Float above. It has no options of its own.

Split

Splits a string on a separator into an array, then returns one element of that array by index.

• Separator — a text field for the string (or character) to split the input on. No default.
• Select — a number field for which index of the split result to return, starting at 0. Defaults to 0.

Worked example: with Separator set to @ and Select set to 1, the Template tab emits the incoming value as a declared variable, then "$qa.split": "@" with a nested "$result": {"$getVariable": "data.1"} — splitting the input on @ and taking element 1 of the result. Wired to the sample XML's <Email> field (ops@acme-shipping.example), that selects the domain half of the address.

Date & Time

Transforms a value into a date, converts between date formats, or outputs UNIX time.

Field	Type	Description	Default
Use Current Timestamp	Checkbox	Ignore the wired input entirely and use the current timestamp instead.	Unchecked
Use Current Date	Checkbox	Ignore the wired input entirely and use the current date instead.	Unchecked
Input Type	Radio (Date String / Epoch Time (Unix timestamp))	What kind of value is wired into the node.	Date String
Input Format	Dropdown (also accepts a typed custom value)	Date/time formatting of the incoming value.	None
Output Type	Radio (Epoch / Custom)	What kind of value the node produces.	Epoch
Output Format	Dropdown (also accepts a typed custom value)	Date/time formatting of the outgoing value, offering presets like YYYY-MM-DD, YYYY-MMM-DD, DD-MM-YYYY, and time-inclusive variants like YYYY-MM-DD HH:mm. Only shown while Output Type is Custom.	None
Validate Date Range	Checkbox	Enable checking whether the date falls within a window around today.	Unchecked
Minimum Days	Number	The date must be at least this many days ago to pass validation. Only shown while Validate Date Range is checked.	None
Maximum Days	Number	The date must be at most this many days in the future to pass validation. Only shown while Validate Date Range is checked.	None
Adjust Winter Time	Checkbox	Adjust the current date for winter time (DST).	Unchecked

Worked example: added fresh with nothing wired in, a new Date & Time node's Output tab already shows a 13-digit epoch-millisecond number (its Output Type defaults to Epoch, and with no input wired the underlying value falls back to the current time). Checking Use Current Date, switching Output Type to Custom, and setting Output Format to YYYY-MM-DD changes the Output to today's date in that format — running it live produced 2026-09-02.

Substring

Extracts a substring from a string by start and end index.

• From — a number field for the starting index of the substring. Defaults to 0.
• Use End — a checkbox for whether to cut the substring off at an end index at all. Checked by default (so a fresh node already has an end index in play, not just a from-index to the end of the string).
• To — a number field for the ending index of the substring. Defaults to 0. Only meaningful while Use End is checked.

Worked example: with From set to 4 and To set to 7, the Template tab emits the incoming value as a declared variable varToParse, then "$varToParse.substring": [0: 4, 1: 7] — taking characters at index 4 up to (not including) index 7 of whatever value is wired into the node.

Logical Operators

OR

Combines two or more values with an OR operator. Has no Options tab of its own; wire two or more upstream nodes into it.

Worked example: added fresh with nothing wired in, the Template tab emits {"$utils.or": []}, and the node's Output stays a $__reserved__result__<id> placeholder — an OR over zero operands doesn't resolve to a value the way AND's does.

AND

Combines two or more values with an AND operator. Has no Options tab of its own; wire two or more upstream nodes into it.

Worked example: added fresh with nothing wired in, the Template tab emits {"$utils.and": []}, and the node's Output already reads True — an AND over zero operands is vacuously true.

NOT

Inverts a boolean value. Has no options of its own.

Worked example: added fresh with nothing wired into its input, the Template tab emits {"$utils.not": undefined}, and the node's Output reads {}.

Condition

Forwards a value based on a condition: three inputs (if, then, else) instead of the usual single or multiple ones, so you wire the condition and both branches in directly. It has no Options tab of its own — confirmed live: with nothing wired in, its Template tab reads Empty and the node shows Failed to evaluate.

Switch Case

Evaluates multiple conditions using a switch-case structure. It has no Options tab of its own; instead it takes a condition input, a multi cases input (fed by one or more Case Definition nodes), and an optional default input, so you build the branching by connecting nodes rather than filling in fields.

Equal

Checks if two values are equal.

• Invert — a checkbox for whether to check for inequality instead of equality. Unchecked by default.

Worked example: added fresh with nothing wired into either input, its Output already reads True — both (unwired) sides evaluate to undefined, and undefined equals undefined.

RegExp Test

Checks if a value matches a regular expression.

Field	Type	Description	Default
Pattern	Text	The regular expression pattern to test against.	None
Global	Checkbox	Match every occurrence of the pattern rather than stopping at the first.	Unchecked
Case Insensitive	Checkbox	Whether the match ignores letter case.	Unchecked

Mathematical Operators

Add

Adds two or more values together. Has no Options tab of its own; wire two or more upstream nodes into it.

Worked example: added fresh with nothing wired in, the Template tab emits {"$math.sum": []} — an empty list of addends — and the node's Output already reads 0, the sum of zero values.

Multiply

Multiplies two or more values together. Has no Options tab of its own; wire two or more upstream nodes into it.

Worked example: added fresh with nothing wired in, the Template tab emits {"$math.multiply": []} — an empty list of factors.

Round

Rounds a value to the nearest integer. Has no options of its own — confirmed live: its Template tab is just {"$math.round": undefined} until you wire a value in.

Ceil

Rounds a value up to the nearest integer. Has no options of its own.

Floor

Rounds a value down to the nearest integer. Has no options of its own.

Maximal

Gets the largest of two or more values. Has no Options tab of its own; wire two or more upstream nodes into it.

Worked example: added fresh with nothing wired in, the Template tab emits {"$math.max": []} — an empty list of candidates.

Subtract

Subtracts a fixed value from the incoming value.

• Subtract — a number field for the value to subtract. Defaults to 0.

Worked example: with nothing wired into the node and Subtract set to 3, the Template tab emits the incoming value as a declared variable 0 (i.e. undefined coerces to 0), then "$math.minus": [0: undefined, 1: 3], and the node's Output reads -3.

Divide

Divides the incoming value by a fixed divisor.

• Divisor — a number field for the value to divide by. Defaults to 1.

Worked example: with nothing wired into the node and Divisor set to 4, the Template tab emits "$math.divide": [0: undefined, 1: 4], and the node's Output reads 0 (undefined divided by 4 resolves to 0 rather than NaN).

Less Than, Less Than or Equal, Greater Than, Greater Than or Equal

Compare the incoming value against a fixed value and return whether the comparison holds.

• Each node has one number field, named after the node itself (Less Than, Less Than or Equal, Greater Than, Greater Than or Equal), for the value to compare the incoming value against. Defaults to 0. Its description reads "Check if the incoming value is [comparison] this value."

Worked example: Less Than added with nothing wired in and its field left at the default 0 — the incoming (unwired) value is undefined, which is not less than 0, so Output reads False.

Tables

Compose Table Columns

Constructs a table by automatically identifying its columns from a marker in the file.

Field	Type	Description	Default
From	Selector	Marker in the file to compose the table from. Clicking the selector button and then a spot in the file preview without a specific value under the cursor falls back to the document root ($inputdocument..@); the selector accepts any node in the file, not just table-shaped ones.	None
Table Definition in Header	Checkbox	Whether the table's column definitions start at the header row.	Checked
Lines	Number	How many lines to skip from the marker before the table starts. Only shown when Table Definition in Header is unchecked.	1
Compose	Checkbox	Enable a different algorithm for inferring the table's structure.	Unchecked

Worked example: with From set to the document root and the other options left at default, the Output reads { "#$composeTableColumns": { "from": "$inputdocument..@", "lines": 1, "fromLine": 0, "compose": false } } — lines and compose are always present in the generated template regardless of which options are visible in the UI.

Cell

Gets the value of one cell within a table, addressed by row and column number.

• Target Row — a number field for the row of the cell. Defaults to 0.
• Target Column — a number field for the column of the cell. Defaults to 0.
• Iterate — a checkbox to iterate over the cell. Unchecked by default.
• From — the marker used to compose the table this cell belongs to. No default.
• From Line — the line used to compose that table. Defaults to 0.
• Columns — a graph-derived set of column definitions used to index the table's cells: an Open graph / Clear graph pair, the same as Switch Case's cases — you wire in column definitions rather than fill in a field.

Worked example: with Target Row set to 1 and Target Column set to 2 (all other fields left at default), the Output reads { "#1,2$cell#": { "fromLine": 0 } }.

Column

Iterates over a single column within a table, by column number.

• Column — a number field for which column to iterate over. Defaults to 0.

Worked example: with Column set to 3, the Output reads #>$column#3.

Iterators

Count Occurrences

Iterates over a value that appears multiple times in the file, used to relatively reference fields to extract on each occurrence.

• Count Occurences — a selector (note the source's spelling) for the text in the file to iterate over. No default.
• Refer Back — a text field that fine-tunes the starting point of each occurrence: from the beginning of the line, or a specific character/word before the keyword. No default.

Worked example: selecting a field inside the sample XML's repeating <Item> block sets Count Occurences to a path like $inputdocument.Order.Items.Item.Quantity.@.@, and the Output reads { "countoccurences": "$inputdocument.Order.Items.Item.Quantity.@.@" }.

Iterate Table

Iterates over a table to extract values.

Field	Type	Description	Default
From Marker	Selector	Marker in the file where the table starts.	None
To Marker	Selector	Marker in the file where the table stops.	None
From Line	Number	How many lines to skip from the marker before the table starts.	0
Shift Rows	Number	How many rows to skip from the start of the table before iterating over values.	0
Find By Columns	Checkbox	Enable a different compose algorithm.	Unchecked
Columns	Graph-derived	Column definitions used to index the table's cells.	—
Skip	Graph-derived	Which rows to skip.	—

Worked example: added fresh with nothing wired into any field, the node's Output already resolves (no markers are required for it to produce something) to { "table": { "findByColumns": false, "fromLine": 0, "shiftRow": 0 } } — the three visible defaults (Find By Columns, From Line, Shift Rows), nested under a table key. From Marker and To Marker don't appear in this output because nothing was selected for them.

Get From List

Gets element(s) from a list.

Field	Type	Description	Default
Value	Selector	The value to extract from the list.	None
Reference	Selector	The list to iterate over.	None
Skip	Graph-derived	Whether the current element should be skipped.	—
Return Mode	Radio (Entire List / Single Element)	Whether to return the whole list or one element.	Entire List
Target Element	Number	Index of the element to extract. Only shown once Return Mode is set to Single Element.	0

Worked example: added fresh with nothing wired into Value or Reference and Return Mode left at its default Entire List, the node's Output doesn't fall back to a placeholder like the math nodes do — it shows an error state instead: "Failed to evaluate — Template did not return a node result."

Sum From List

Sums the elements of a list.

Field	Type	Description	Default
Value	Selector	The value to extract from the list.	None
Reference	Selector	The list to sum over.	None

Worked example: added fresh with nothing wired into Value or Reference, the node's Output shows the same error state as Get From List: "Failed to evaluate — Template did not return a node result."

Container Iterator

Defines the quantity of containers to iterate over — used when a document's repeating structure is driven by a count field rather than by a literal repeated block.

• Quantity — a selector for the number of containers defined in the file. No default.
• Variable Declaration — a text field naming the variable to declare, for when this container iterator is itself a self-defined variable. No default.

Worked example: with Quantity selected against the sample XML (a click that resolved to the document root, $inputdocument..@, rather than a specific field), the node's Output — truncated in the preview — starts { "template": { "_containerid": "$ITERATOR1" }, "data": { "#repeatItems": [ { "repeat": { "#parseInt": "$inputdocument..@" }, "_containerid": "$CURRENT_COUNTER" …: the generated template declares an iterator ID, parses the selected value to an integer, and repeats a nested block that many times.

Requests

Generic Request

Makes a request to a database for custom logic.

Field	Type	Description	Default
Database	Text	The database to fetch data from.	None
Collection	Text	The collection to fetch data from.	None
Target	Text	The value to read from the resulting data.	None

Worked example: with Database set to morphjs, Collection to customer, and Target to CODE, the Template tab emits {"$mongoRequest": [{"$db.customer.findOne": {}, "$result": {"$getVariable": "CODE"}}, "morphjs", ["customer"]]} — the three fields become, in order, the query's result shape (the $result value bound to the Target field), the database name, and a one-element array holding the collection name. With nothing else wired in, the node's Output stays a $__reserved__result__<id> placeholder, since resolving it means actually issuing the query.

Vessel Request

Fetches vessel information from a database. Same three fields as Generic Request, but fixed and non-editable: Database defaults to morphjs, Collection to resource, and Target to CODE.

Worked example: added fresh with nothing wired into it, the node still resolves — because its Database/Collection/Target are fixed rather than depending on anything upstream — and its Output shows GERD, an existing resource code from the dev database.

Case Definition

Case Definition

Specifies one condition within a Switch Case node's structure.

• Match — a text field for the value to compare against the condition. No default.
• Result — a text field for the value to return when the condition matches. No default.

You add one Case Definition node per branch and feed them all into the Switch Case node's cases input (see the Switch Case screenshot above, which shows two Case Definition nodes feeding it).