> 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/guides/development/how-to-use-visual-data-mapper.md).

# How to use Visual Data Mapper

Data mapping made both formal and easy.

Visual Data Mapper, or VDM, is a visual low-code mapping tool in Frends for creating source-to-target data transformations inside a Process. It helps you map fields between input and output structures without writing full custom C# code for common transformation scenarios. VDM is useful when you need to transform data from one schema into another, such as converting an API response into the format required by another system.

This guide explains how to configure output schemas on source shapes, add VDM to a Process, select source and target schemas in the VDM editor, create mappings, use expressions, generate mappings with Frends Assistant, and reference the mapping result later in the Process.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2F6kQ9UDVdoFfmLn6uFJyx%2Fimage.png?alt=media&amp;token=1b79945c-0008-4856-b469-5db13c2123c3" alt=""><figcaption><p>Visual Data Mapper within a Process.</p></figcaption></figure>

## Prerequisites

Before using VDM, you need access to a Frends Tenant where VDM is available, meaning Frends 6.4 or later.

You should also have a Process where data has already been produced or received before the VDM shape. The source data can come from an earlier Task, Code shape, Subprocess, DMN shape, another VDM shape, or a variable created earlier in the Process. The VDM editor can show available source schemas from previous shapes and variables, provided that the source has a schema configured.

You also need to know the expected target structure. The target schema defines the shape of the data that VDM creates as its output.

## Configure the schema on a source shape

For VDM to display the fields of a source shape in the visual editor, that shape needs to have an output schema configured. The schema describes the structure and data types of the data the shape produces. Without it, VDM can offer the shape as a source option but cannot display its individual fields for visual mapping.

Open the source shape in the Process editor — for example, a Task or Code shape — and find the schema configuration option. A button labeled **Add Schema** or **View Schema** is visible on the shape panel. Clicking it opens the schema editor where you can define or review the output structure of that shape.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FdU7n0lR9FLvlgaudLkHo%2Fimage.png?alt=media&amp;token=bb47e80d-811f-4acd-9405-19f7229cb8be" alt=""><figcaption><p>View schema replaces Add schema, if a schema is already added.</p></figcaption></figure>

### Manually defining the schema

The schema editor offers two ways to provide the schema. You can type or paste the schema directly into the editor, or use the **Import schema** button to provide either a sample JSON value or file, or a JSON schema file.

Typing or pasting directly into the editor is useful when you already know the exact schema structure and want to write or edit it by hand.

The **Import schema** button opens an import dialog where you can provide the schema as a file. Two file types are accepted. If you have a sample JSON response from the source system, you can import that and Frends will infer the schema structure and data types from the values in the sample. For example, a sample JSON for a customer object might look like:

```
{
  "id": "123",
  "firstName": "Jane",
  "lastName": "Smith",
  "email": "jane@example.com",
  "isActive": true
}
```

If you already have a JSON schema file available — for example, one provided by the API vendor or exported from another tool — you can import that directly instead.

After the schema is defined by either method, save it to attach it to the shape. The schema is stored on the shape itself and becomes available to VDM when that shape is used as a source.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FhBTzi5vfJrpHGiSwrl4N%2Fimage.png?alt=media&amp;token=bd837f49-b423-4600-9b6c-17aa69646769" alt=""><figcaption><p>JSON schema editor for a shape.</p></figcaption></figure>

Schemas can be added to Task, Code and Assign Variable shapes, as well as Call Subprocess and DMN Task shapes. AI Connector and Shared State shapes are currently not included, and need to be taken through a Code shape for example to be used with VDM. You can also add a schema for Process Variables in the Variables tab in Process Editor.

### Generating the schema from a unit test

Instead of writing the schema by hand, you can run a unit test on the source shape and generate the schema directly from the actual execution result. This is useful when the output structure is complex or when you want to make sure the schema matches what the shape actually returns in practice.

Open the source shape and switch to the unit test view. Provide the necessary input values for the test and click **Run test** to execute the shape. When the execution completes successfully, the result is displayed in the test panel. From there, use the option **Generate a schema** to apply the schema based on the result. Frends infers the schema from the structure and data types of the returned data and saves it to the shape.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2Fo5vifmVutxj6x6PJtNc3%2Fimage.png?alt=media&amp;token=74f11b84-6bff-4657-82c5-c744b95ead92" alt=""><figcaption><p>Unit test allows obtaining sample JSON to generate schema from.</p></figcaption></figure>

Once the schema is saved, the shape becomes available in the VDM source selector and its fields are shown in the VDM source panel ready for mapping.

## Add Visual Data Mapper to a Process

VDM is added to a Process as a separate shape in the Process editor. Place it at the point in the Process where the source data is already available and the transformed output is needed for later steps.

After adding the VDM shape, give it a clear name. The name is important because the mapping result can be referenced later in the Process by using the VDM result reference, such as `#result[Map customer data]`.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FgSNcWcPATREZ7EjeuIAD%2Fimage.png?alt=media&amp;token=245f476a-141f-48db-bfe4-f67725dc8793" alt=""><figcaption><p>Visual Data Mapper shape without configuration made.</p></figcaption></figure>

### Open the VDM editor

Select the VDM shape in the Process Editor to open its configuration tab, and select **Configure data mappings** to open the editor. The VDM editor provides a separate mapping view where you can see the source schema, the target schema, and the mapping canvas.

The editor is designed around a source-to-target workflow. The source side represents the data you already have, and the target side represents the data you want to produce. You create the transformation by connecting source fields to target fields and by defining mapping expressions where needed.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FHkp253DaEEIAmOWKbrOU%2Fimage.png?alt=media&amp;token=cbe448ef-31f9-4514-9f85-e13433a65d9c" alt=""><figcaption><p>Visual Data Mapper editor.</p></figcaption></figure>

## Configure the source schema

The source schema describes the structure of the data that VDM reads. In the VDM editor, select the source from the available source selector. Available sources can include earlier Process shapes and variables, such as `#var.customer`, `#result[Get Customer]`, or other supported shape outputs.

If the selected source does not have a schema, the editor cannot show its fields for visual mapping. See the section above on how to configure the schema on the source-producing shape before continuing.

## Configure the target schema

The target schema describes the structure of the output that VDM creates. Define or import the target schema in the VDM editor. Schemas can be added directly in the schema editor, or from sample JSON input or file upload through the **Import schema** button.

The target schema should match the data structure expected by the next system or later Process step. For example, if the next Task sends data to an API, the target schema should match the request body expected by that API.

## Create field mappings

After both schemas are available, create mappings between source and target fields. In the visual editor, connect a source field to a target field by drawing a line between them.

### Understand mapping tokens

The mapping type is indicated by the color of the mapping token — the marker that appears on the target field end of the line.

A purple token indicates a direct mapping, where the target field receives its value directly from a source field. A blue token indicates a user customized mapping, where the value is produced with an expression or transformation. A green token indicates a static mapping, where the target field always receives a fixed value regardless of the source data.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FC3QRSZ8C72EZBtFlcvp3%2Fimage.png?alt=media&amp;token=2136bbaa-a745-40e8-83aa-405ce2e0de66" alt=""><figcaption><p>Mapping tokens in VDM.</p></figcaption></figure>

Generated mappings should be treated as a starting point. Review the proposed mappings before using them in a Process. Check that each target field receives the correct value, that data types are correct, and that any business-specific transformation rules are included.

After accepting generated mappings, you can edit the mapping lines, target fields, and expressions in the normal VDM editor view.

## Use static values, expressions, and text values

Each mapping in VDM has a value type that determines how the target field's value is produced. The key distinction is whether the value depends on source data or is always fixed.

A static mapping sets a target field to a value that never changes, regardless of the source data. Static fields have no source mapping line and do not reference `#source` at all. This is useful for fixed system identifiers, constant status codes, or integration-specific metadata. For example, a target field called `sourceSystem` could always be set to `Frends`, or a field called `status` could always be set to `New`. Static mappings are indicated by a green mapping token on the target field.

When a target field's value depends on source data, you use either a C# expression or a text value with handlebars syntax. Which options are available depends on the type of the target field.

For string target fields, you can choose between a C# expression or a handlebars text value. A C# expression follows the same rules as the Assign Variable shape — it must be written as a single line that resolves to a value, and cannot contain control structures such as `if`, `else`, or `foreach`. A text value lets you write a template string where references in `{{handlebars}}` syntax are replaced with their values at runtime — this is often more readable for simple string compositions and also supports conditional blocks and loops. Both can reference `#source` to read source data.

For numerical, boolean, and object target fields, a C# expression is required. The same one-liner rule applies — the expression must resolve directly to a value of the correct type.

The same text and expression modes are also available for static mappings — the difference is simply that the value you write does not reference `#source`.

### Conditional expressions and loops

Handlebars text values support conditional blocks and loops, making them well suited for cases where the output depends on source data or needs to iterate over a collection. C# expressions do not support control structures, so conditional and loop logic must be handled in handlebars text mode or moved to a Code shape.

Conditional blocks follow this format:

```
{{#if condition}}
value when condition is true
{{else}}
value when condition is false
{{/if}}
```

For example, you might set a customer type field based on whether a business ID is present in the source:

```
{{#if #source.businessId}}
Company
{{else}}
Person
{{/if}}
```

### Loop expressions

For arrays and collections, low-code expressions support loop syntax with `{{#each}}`. Inside the loop, `{{this}}` refers to the current item, and `{{@index}}` refers to the current item index.

```
{{#each #source.items}}
{{this.name}}
{{/each}}
```

Use loops when you need to create repeated output from a source collection. For schema-based array mappings, VDM can also infer per-element mapping from the source and target schemas in supported cases.

## Map arrays and nested objects

VDM can be used with nested objects and arrays when the schemas describe those structures. Expand complex fields in the source and target panels to map inner fields.

For nested objects, map the individual fields under the object. For example, map `#source.customer.address.street` to `customerAddress.street`, and `#source.customer.address.city` to `customerAddress.city`.

For arrays, the mapping depends on whether you are mapping the whole array or mapping values for each array element. A target array can use a whole-array mapping or per-element mappings, but not both at the same time. Similarly, a target object should not be configured with both a whole-object mapping and separate per-field mappings.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FliIPMPzEZBQ2fxViiD85%2Fimage.png?alt=media&amp;token=5342bd3e-e12b-444d-8637-c0b6cb140d25" alt=""><figcaption><p>Mapping array's field value to another array.</p></figcaption></figure>

### Per-element array mapping

In schema-driven per-element array mapping, VDM can create one target element for each source element. The source array works as the driver for the target array. Values from the current source item are then mapped to fields in the current target item.

This is useful when transforming a list of records from one format into another. For example, you can map a source array called `orders` into a target array called `salesOrders`, with each source order producing one target sales order.

If an array mapping uses multiple source arrays in the same target scope, the mapping must be clear enough for VDM to infer the correct driver. Conflicting array drivers can cause compile-time validation errors.

## Use the VDM result in the Process

The output of a VDM shape is available as a result reference value, such as `#result[Map Customer]`. The result is a `JToken`, which means it can represent JSON-style values such as objects, arrays, strings, numbers, booleans, and null values.

For example, if the VDM shape creates a request body for an API call, use the mapping result as the body input in the following HTTP Task.

<figure><img src="https://4223974572-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F0p415NUmUmiF4ayjI81L%2Fuploads%2FsUzAwu8Nicc1Gal9ZMEL%2Fimage.png?alt=media&amp;token=a8c7c009-ab29-485f-973a-4c67bd25940e" alt=""><figcaption><p>Using the #result reference value from VDM shape.</p></figcaption></figure>


---

# 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/guides/development/how-to-use-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.
