Data Mapping

Data Mapping

Article Type: Concept / How-To Audience: Application Administrators, Developers Module: Orchestration / Data Flow Applies to Versions: Fuuz Platform 2024.1+

1. Overview

The Data Mapping Designer provides a visual, diagram-based approach to data transformation in the Fuuz platform. Unlike code-based transforms, data mappings represent field-to-field transformations graphically, making complex data restructuring intuitive and error-resistant.

What is a Data Mapping?

A data mapping is essentially a field-to-field data transformation represented in a visual, diagram-based format. Nodes in a data mapping represent values, and links between nodes represent data sources and targets.

At their simplest, data mappings consist of two core components:

• A pair of JSON schemas defining the input/output types
• A set of links defining how to transform from the input shape to the output shape

A basic mapping from a Fuuz Calendar to an object with id/label properties

Data Mapping vs. JSONata Transform

The visual mapping shown above is functionally similar to the following JSONata transform:

{
  "id": id,
  "label": name
}

While the transform is simpler in this example, the data mapping provides significant advantages that become critical in complex enterprise scenarios.

Key Advantages of Data Mappings

Advantage	Description
Dual Schema Validation	Input/output schemas provide validation on both sides of the mapping, preventing cases where JSONata transforms may behave unexpectedly for slightly-incorrect inputs
Design-Time Error Detection	The Data Mapping Designer catches mistakes visually during design, not at runtime
Type Mismatch Detection	Mapping a number field to a string field is visually indicated as an error
Missing Property Detection	Required output fields without mapped inputs are flagged immediately
Format Validation	Mismatched string formats (e.g., date-time vs. email) are detected during design
Visual Documentation	The diagram itself serves as documentation of the transformation logic

The designer catches type mismatches like mapping a number to a string

Missing required properties are flagged during design

2. Creating and Editing Mappings

Accessing the Data Mapping Designer

To create a new Data Mapping:

1. Open the Data Mapping Designer
2. Select File > New from the menu bar
3. Define the input and output JSON schemas in the dialog that appears

Defining Input and Output Schemas

When creating a new mapping, you must define a pair of JSON schemas describing the expected input structure and desired output structure.

Note: You are free to edit the input/output schemas of your mapping at any time, so don't worry if you aren't 100% sure what they should look like at first.

An example of defining input/output schemas when creating a new mapping

Initial Diagram Structure

Once the schemas are provided, the designer populates with a diagram containing two nodes:

• Input Schema Node — Represents the incoming data structure
• Output Schema Node — Represents the target data structure (the "result" of the mapping)

A freshly-created data mapping containing the schema nodes

Selecting Fields to Map

Each schema node displays a dropdown at the bottom allowing you to choose which fields from the schema should appear as connectable ports on the node.

Choose fields to map using the dropdown at the bottom of each schema node

Creating Links Between Fields

Once your fields are chosen, connect the input and output fields by dragging from one port to another:

1. Click and hold on an output port of the source node
2. Drag to the input port of the target node
3. Release to create the link

You can see which ports are compatible while dragging links

Visual Error Indicators

The designer provides immediate visual feedback for mapping errors:

• Red Links — Type mismatch, format mismatch, or other validation error between connected fields
• Warning Icons — Missing required mappings or potential issues
• Green/Normal Links — Valid, compatible field mapping

Mistakes are represented as red links in the diagram

Using Context Menus

Right-click anywhere in the diagram to access context menus for adding nodes and performing other actions:

• Right-click on canvas — Add new nodes to the diagram
• Right-click on nodes — Access node-specific options
• Right-click on fields — Access field-specific options
• Right-click on links — Delete or modify connections

Saving Your Mapping

Save your mapping using:

• Keyboard shortcut: Ctrl+S
• Menu option: File > Save

3. Diagram Nodes

The Data Mapping Designer supports various node types to handle complex transformation scenarios.

Core Schema Nodes

Node Type	Description
Input Schema	Represents the incoming data structure. Fields from this node are the sources for your mappings. Created automatically based on your input JSON schema.
Output Schema	Represents the target data structure and the "result" of the mapping. Fields on this node are the targets for your mappings. Exactly one Output Schema node is required.

Transformation Nodes

Node Type	Description
Filter	Filters arrays based on conditions. Can return zero, one, or multiple results depending on the filter criteria.
Lookup Table	Performs key-based lookups against reference data. May produce zero results if the lookup key is not found.

Important: Filter and Lookup nodes can produce zero results on certain inputs. If your output schema expects a single object but these nodes return nothing, the mapping will throw a validation error at runtime.

4. Testing Data Mappings

Using the Test Cases Panel

To test your data mapping with sample data, use the Test Cases panel located to the left of the diagram.

Creating a Test Case

1. Click the plus button (+) in the Test Cases panel to add a new test case
2. Enter your input data into the Input Payload editor that appears
3. Click the play button to execute your mapping against the provided input
4. Review the output result displayed in the panel

An example test case in the Test Cases panel

Saving Test Cases

If you would like to save a test case for reuse:

1. Click the save button that appears next to the test case name at the top of the panel
2. Optionally, edit the test case's name and description using the adjacent pencil icon

Important: Test cases may be saved using the save button in the Test Cases panel, but they will not autosave with the diagram! This is intentional to allow developers to experiment with sample input data without fear of accidentally overwriting an existing test.

Test Case Properties

Property	Type	Description
name	String	The name of the test case (unique per mapping)
description	String	Optional description of what the test case validates
payload	JSON	The input payload to be used for this test case
result	JSON	The expected output result for validation
active	Boolean	Whether this test case is active
metadata	JSONObject	Optional additional configuration

5. Using Mappings in Data Flows

The Data Mapping Node

Once you've deployed your data mapping, you can use the Data Mapping node in the Flow Designer to execute it, just like you would with a saved script.

Using the Data Mapping node in the Flow Designer

Node Configuration

Property	Description
Data Mapping	Select the deployed data mapping to execute
Input	The message payload or expression providing input data (must match input schema)
Output	Where to store the mapping result (typically msg.payload)

Critical: Error Behavior

Important: Data mappings will throw errors if the input schema fails to validate, but they will also throw errors if they produce a result that doesn't match their own output schemas.

For example, a mapping that expects to return a single object may use a Filter or Lookup node in a way that inadvertently produces zero results on certain inputs. The mapping will catch this and throw an error instead of returning undefined.

There is no way to disable this behavior. Therefore, treat Data Mapping nodes the same way you would treat Validate nodes if it's important for your flow to fail gracefully.

Recommended Error Handling Pattern

To handle mapping failures gracefully:

1. Place a Try/Catch node before the Data Mapping node
2. Connect the Data Mapping node inside the Try block
3. Handle the mapping failure in the Catch block

+-------------+     +-----------------+     +-------------+
|  Try/Catch  |---->|  Data Mapping   |---->|   Continue  |
+-------------+     +-----------------+     +-------------+
       |
       | (on error)
       v
+-----------------+
|  Handle Error   |
+-----------------+

6. Versioning and Deployment

Version Management

Each data mapping supports multiple versions, allowing you to iterate on your transformation logic while maintaining a history of changes.

Version Property	Description
number	The version number identifier
description	Optional description of changes
diagram	The JSON containing the visual diagram
mapping	The compiled mapping JSON for the engine
inputSchema	The input schema for this version
outputSchema	The output schema for this version
deployed	Boolean indicating if this version has been deployed

Deployment Process

When you deploy a data mapping version, a deployment record is created with the following label format:

<MAPPING NAME>: <VERSION>: <mm-dd-yy hh:mm:ss>

For example: OrderTransform: 1.2: 01-15-24 14:30:45

Substitution Pattern

Data mappings support a substitution pattern for environment-specific overrides:

• substitutesDataMapping — Configure one mapping to replace another's effective deployment when active
• substitutedByDataMapping — Reference to the mapping that substitutes this one

Note: This pattern is useful for environment-specific mapping overrides. For example, a QA environment might have a substitute mapping that provides test-specific transformations without modifying the production mapping.

7. Troubleshooting

Issue	Cause	Fix
Red links appear in diagram	Type mismatch between source and target fields	Check field types match. Use transformation nodes if type conversion is needed.
Mapping throws error at runtime despite valid input	Output validation failed (Filter/Lookup returned zero results)	Adjust output schema to allow arrays or nullable types, or wrap with Try/Catch.
Test case changes not persisting	Test cases require explicit save (not autosaved)	Click the save button next to the test case name.
Cannot find deployed mapping in Flow Designer	Mapping not deployed or not active	Verify the mapping has been deployed and active flag is true.
Mapping using wrong deployment	Substitution pattern in effect	Check if another mapping has substitutesDataMappingId set. Review effectiveDeployment vs currentDeployment.
Input schema validation failing	Incoming data doesn't match expected schema	Use debug nodes before the Data Mapping node to inspect actual payload.
Cannot connect ports in designer	Incompatible port types	The designer shows compatible ports while dragging. Add transformation nodes if needed.
Schema changes not reflected	Using old deployment version	Save a new version and redeploy.

8. Revision History

Version	Date	Editor	Description
1.0	2026-01-01	Fuuz Documentation Team	Initial Release

See Also

• Data-Flow-Nodes-Reference
• Transform-Nodes-Data-Flows
• Script-and-Validation-Nodes
• Flow-Control-Nodes
• Custom-Fuuz-Only-JSONata-Library

---

Source: support.fuuz.com