> For the complete documentation index, see [llms.txt](https://docs.frends.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.frends.com/reference/shapes/activity-shapes/visual-data-mapper.md).

# Visual Data Mapper

Create source-to-target data mappings visually in your Processes.

Without mapping data between systems, integrations often end up passing along data in a format that only one system understands. While this can be handled with code, many mappings are easier to create, review, and maintain visually. In Frends, Visual Data Mapper can be used as part of a Process to transform structured source data into a target structure that can be used by the following shapes.

With Frends 6.4, Visual Data Mapper provides a dedicated shape for common JSON mapping scenarios, including direct field mappings, static values, mappings that use low-code expressions, and mappings generated with Frends assistant.

## What is Visual Data Mapper?

For creating visual data mappings in your Processes, a shape called Visual Data Mapper is available in Frends Processes. Visual Data Mapper allows selecting source data, defining the target schema, and configuring mapping rules between the source and target fields. The shape then produces a structured result that can be used for further handling in the Process.

<figure><img src="https://3198802258-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1H5SQ92uIfBOYNIeoUAc%2Fuploads%2FQonmkISmA1muS81V8tRc%2Fimage.png?alt=media&amp;token=9f84653f-8282-464b-87b5-53feef05b949" alt=""><figcaption><p>Visual Data Mapper can be used to perform common source-to-target JSON transformations within the Process.</p></figcaption></figure>

While the Visual Data Mapper will not, and should not, replace all transformation logic by itself, it is a practical tool for mappings where the source and target data structures can be described with schemas. For more complex transformation logic, the Code shape remains available.

## Usage

In order to use Visual Data Mapper, add it to your Process canvas and connect it as part of your Process using two Sequence Flows. Like other activity shapes, Visual Data Mapper must be connected between a Trigger and a Return or Throw shape, i.e. the Process cannot start or end with an activity shape. You can also optionally connect an Intermediate Return or Catch shape to Visual Data Mapper as an alternative execution path.

Once added to your Process, give the shape a display name and configure the settings shown in the shape configuration panel. The panel shows the Strict schema validation toggle, the currently selected Source, a summary of Mapping rules, and the Configure data mappings button. The Source and Mapping rules values shown in the shape settings are edited by pressing **Configure data mappings**.

Source data can be selected from available Frends reference values, such as `#var` and `#result`. The selected source should have a **JSON schema** so that the Visual Data Mapper can show the available fields in the source panel. The **target schema** defines the structure of the result that the Visual Data Mapper produces.

Mappings are created by connecting fields from the source schema to fields in the target schema, by setting a value directly for a target field, or by generating an initial mapping with Frends assistant. Depending on the target field type, the mapping can be handled as text or as an expression. String targets can use text mappings, while non-string targets use expression mappings.

### Mapping expressions

Once the source and target schemas have been defined, you can start creating mapping expressions between the fields. Mapping expressions define what value is written to each target field when the Visual Data Mapper shape is executed.

<figure><img src="https://3198802258-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1H5SQ92uIfBOYNIeoUAc%2Fuploads%2F8ayvuQv3pViQ6Yx6Vfs7%2Fimage.png?alt=media&amp;token=09454d85-cc84-47f6-a555-ecdaf7b12d93" alt=""><figcaption><p>Visual Data Mapper editor.</p></figcaption></figure>

A mapping can be:

* **direct one-to-one** mapping from a source field to a target field,
* **many-to-one** mapping where multiple source values are combined into one target value,
* **one-to-many** mapping where one source value is used in multiple target fields,
* or **static value** set directly for a target field.

Source values are referenced from the selected source with `#source`. For example, a source field called `firstName` can be referenced as `#source.firstName`.

For **string target fields**, mappings can be written as **text mappings with handlebars**. Text mappings can contain static text and embedded source references.

```
{{#source.firstName}} {{#source.lastName}}
```

For **non-string target fields**, mappings are written as **expressions**. The expression should return a value that matches the type of the target field.

```
#source.amount + #source.tax
```

Expression mappings can also be used when a string target needs more **explicit logic** than a simple text mapping.

For **boolean target fields**, the expression should return a boolean value.

```
#source.isActive && #source.isVerified
```

**Static values** can be **set directly on target fields** when the value does not need to come from the source. This is useful for values such as source system identifiers, fixed status values, or other metadata that should be included in the mapped output.

### Generating mappings with Frends assistant

Instead of creating all mappings manually, you can also generate an initial mapping with Frends assistant from the Visual Data Mapper editor. The Generate mapping with Frends assistant button is available in the Target panel of the editor, next to the target schema controls, when both source and target schema have been set.

When generating mappings, Frends assistant uses the selected source schema and the target schema to suggest mapping rules between the fields. The generated mappings are added to the editor as normal mapping rules, where they can be reviewed and modified before saving.

This is useful when the source and target schemas contain similar field names or structures, or when you want to create a first version of the mapping quickly and then adjust the details manually. Generated mappings should be reviewed before the Process is tested or activated, especially when target field types, naming conventions, or required values differ between systems.

## Configuration

To set up a Visual Data Mapper, add the shape to Process canvas and connect it as part of your Process. After that, you can configure the parameters shown in the shape settings before opening the Visual Data Mapper editor.

The following configuration parameters are available for Visual Data Mapper.

### Display name

Shapes can be given a display name in Frends Processes to distinquish them from each other. Shape's display name has no technical purpose and is only for documentational and visual purposes only. For shapes returning a #result reference value, the display name can be used to specify which result is meant.

Display name is given to the shape by double-clicking it on the canvas or through its configuration parameters.

### Strict schema validation

Toggle option to select whether the Visual Data Mapper should throw an exception during execution if the result does not match the target schema. When disabled, the Visual Data Mapper allows more flexible output handling.

The setting is disabled by default.

### Source

Source shows the currently selected source element for the mapping. If no source has been selected, the shape settings show that no source is selected.

The Source value shown in the shape settings is edited by pressing Configure data mappings. In the Visual Data Mapper editor, the source is selected with the source selector and can use supported Frends reference scopes such as `#var` and `#result`.

### Mapping rules

Mapping rules shows a summary of the mappings currently configured for the shape. If no mappings have been configured, the shape settings show that no mapping rules are configured.

The Mapping rules shown in the shape settings are edited by pressing Configure data mappings.

### Configure data mappings

Opens the Visual Data Mapper editor, where the source element, target schema, and mapping rules are configured.

When no mappings have been configured yet, this action is shown as the main way to start configuring the shape. When mappings already exist, the same action can be used to edit the selected source, target schema, and mapping rules.

## Mapping editor

The Visual Data Mapper editor is used to configure the source, target schema, and mapping rules. The editor shows the source and target schemas in separate panels and provides visual feedback for the mappings between them.

### Draw lines

Controls whether visual connection lines are shown between mapped source and target fields. When enabled, the mapping editor shows visual lines between connected fields. When disabled, the mappings can still be reviewed through target field tokens.

### Show data tokens

Controls whether mapped target fields display data tokens. Data tokens indicate how target fields are mapped and provide access to edit the mapping. Tokens can be used to identify direct mappings, mappings modified by user, static values, and invalid mappings.

### Source panel

The source panel shows the schema of the selected source element. The source can be selected from supported Frends reference scopes such as `#var` and `#result`. For example, a Process variable can be selected with `#var.sourceVariable1`.

In order to use Visual Data Mapper with a data source, the source has to have a schema created for it. When the selected source has a JSON schema, the source panel displays the schema as a tree. If the selected source does not have a schema, the Visual Data Mapper cannot show the source fields for visual mapping.

### Target panel

The target panel shows the schema of the output that the Visual Data Mapper creates. Target fields can receive values from source fields, static values, expressions, or mappings generated with Frends assistant.

Schemas are handled as JSON Schema. The target schema is edited and imported through the Edit schema modal. Schema import is not configured directly from the shape settings.

If no target schema has been defined, the editor shows an empty state such as `No target schema defined.` Imported schema content must be valid JSON, and the root of the schema must be an object or an array.

The Target panel also contains the Generate mapping with Frends assistant action. This action creates suggested mapping rules from the selected source schema to the target schema and adds them to the editor for review.

### Target schema

Target schema defines the structure of the result produced by the Visual Data Mapper. The target schema is edited in the mapping editor through the Edit schema modal. The target schema is stored and edited as JSON Schema. Imported schema content must be valid JSON, and the root must be an object or an array.

### Mapping connections

Mapping connections show which source fields are mapped to which target fields. The editor supports drawing connections between source and target schema fields and can show those connections visually in the editor.

For larger schemas, the visual lines can be hidden while keeping the mapped fields visible through data tokens.

### Data tokens

Data tokens indicate that a target field has a mapping. They help show whether the target field is a direct mapping, a static value, modified by user, or an invalid mapping.

The token colors shown in the editor are used to identify the mapping type.

A mapped token can be opened for editing. The edit token mapping modal includes a mapping expression editor and source path selection, allowing the mapping expression, target path, and source paths to be adjusted.

<figure><img src="https://3198802258-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1H5SQ92uIfBOYNIeoUAc%2Fuploads%2FCyNxhL1GyGfT6FeFS4kf%2Fimage.png?alt=media&amp;token=2e3e73be-633a-4f9c-9c4e-0184ecebe9a5" alt=""><figcaption><p>Data Token editor.</p></figcaption></figure>

### Skip logging result and parameters

Toggle option to select if the values of this shape should be included in logging or not. Default is false. If set to true, Process Instance logs will show the result and parameter values of this shape as **<< Omitted >>**.

### Promote result as

Toggle option to select if the result value of this shape should be promoted in the Process Instance list, and an text input field if set to true. Default is false. Promoted values appear in the Process Instance list in their own column along with error and result values. Promoted value column is named with the text input field appearing when this is set to true.

Promoted values are always logged fully in the Process Instance view, regardless of the log level settings.

## Reference Values

Visual Data Mapper provides a `#result` reference value, which contains the mapping result created by the shape.

### #result

\#result reference value can be used to access earlier shape's return value. For Scope shapes, the value is specified using Return shape, while for Task's the #result is populated directly by the Task.

<figure><img src="https://3198802258-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F1H5SQ92uIfBOYNIeoUAc%2Fuploads%2F9iRqFDvw15Wh4ohv6qJe%2Fimage.png?alt=media&amp;token=3add05b6-5fd5-4e20-b954-042730915b53" alt="Example of result reference value being used to return a value from Process."><figcaption><p>Result reference value used to return the Task's result as response from the Process.</p></figcaption></figure>

When Return shape is used to end Scope, Foreach or While shapes, the expression or HTTP content values in the Return shape are available through #result reference value after the Scope.

\#result reference value by default references the last Task's or Scope shape's return value. Instead of unnamed #result reference, you can also use named #result reference value.

### Named #result

Named #result reference value is used with square brackets, much like dictionary's or object's fields would be used, such as #result\[Handle elements] or #result\[HTTP Request]. This way it can be specified which shape's result you are using.

When using named #result reference value with Scope shapes and Return shapes, it should be noted that the #result reference value is named by the Scope shape and not by the Return shape, although the value is specified in the Return shape. Thus, when using the named #result value, such as #result\[Handle elements], the Scope shape's name should be used.

### #result\[name] (JToken)

The value returned by Visual Data Mapper is a `JToken`. This means the result can represent structured JSON data, including objects, arrays, strings, numbers, booleans, and null values.

Nested fields can be referenced according to the structure of the target schema and the generated result.

```
#result[My Data Map].customer.id
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.frends.com/reference/shapes/activity-shapes/visual-data-mapper.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
