Value Mapper

Introduction

The Value Mapper is a visual tool for creating field-to-field data mappings between models. It uses a React-based drag-and-drop builder to define how data flows from a source model to a target model, and generates a Groovy script that performs the mapping.

Value Mappers are accessed from Application Builder > BPM components > Mappers.

Value Mapper List

Value Mapper grid view

The grid view displays all value mappers with an Open mapper button (pencil icon) for quick access to the visual builder.

Creating a Value Mapper

Click New to create a Value Mapper, then save the record to enable the visual builder.

Value Mapper form

Form Fields

Field Required Description

Name (1)

No

Unique name for the value mapper.

Open mapper (2)

 — 

Opens the React visual builder in a panel. Only available after the record is saved (has an ID).

Target (3)

 — 

The target model name (read-only, set by the builder).

Source (4)

 — 

The source model name (read-only, set by the builder).

Script (5)

 — 

The generated Groovy script (CodeEditor, read-only). This is the executable output of the visual mapper.

Script meta (6)

 — 

JSON metadata used by the React builder to reconstruct the visual mapping (hidden field).

Visual Builder

The visual builder opens in an embedded panel and provides a drag-and-drop interface for defining field mappings.

Builder Workflow

  1. Select target model: Choose the model that will receive the mapped data

  2. Select source model: Choose the model from which data will be read

  3. Map fields: Drag fields from the source model to the corresponding fields in the target model

  4. Configure values: For each mapped field, define the source value (field reference, expression, or static value)

  5. Add conditions: Optionally add conditions to individual field mappings

  6. Save: The builder generates a Groovy script and stores it in the script field

The builder supports multiple value source types:

  • Field reference: Map directly from a source model field

  • Expression: Use a Groovy expression to compute the value

  • Static value: Set a fixed value

Use the Value Mapper for repeatable data transformation patterns. For example, create a mapper that converts a sales quotation into a confirmed order, mapping all relevant fields.

Executing a Value Mapper

Wizard Execution

Value Mappers can be executed against a specific record through a wizard popup.

The wizard provides:

Field Description

Value mapper

Select the Value Mapper to execute (M2O: ValueMapper).

Execute

Runs the mapper’s generated Groovy script against the specified record.

The execution context includes hidden fields for modelName and recordId, which identify the record to apply the mapping to.

Executing a value mapper directly modifies database records. Test in a development environment before running against production data.

Groovy Execution Bindings

When a Value Mapper script is executed, the following variables are available in the Groovy script context:

Binding Description

ctx

FullContextHelper class providing create(), find(), filter(), save() methods for record operations.

{modelVariable}

The target record wrapped in FullContext. The variable name is derived from the model class name (first letter lowercased, e.g., saleOrder for SaleOrder).

{modelVariable}Id

The ID of the target record.

time

Current local time (LocalDateTime.now()).

datetime

Current date and time with timezone (ZonedDateTime.now()).

studiouser

The current user executing the mapper (or admin if no user context).

this

The target record wrapped in FullContext (alias for the model variable).

self

The raw target record (not wrapped in FullContext).

parent

The parent context record wrapped in FullContext.

id

The target record’s ID.

log

Logger instance (BpmLoggingHelper) for debugging output.
For JSON models (MetaJsonRecord), the variable name is derived from the JSON model name instead of the Java class name.

Result Handling

After the Groovy script executes, the result is processed as follows:

  • If the script creates a new record (detected when the script starts with def rec = ctx.create(), the created record is automatically opened in a form view for the user to review.

  • Otherwise, the execution completes silently and the current view is refreshed.

BPM Integration

Value Mappers can be referenced from BPM processes through the mapper builder dialog. When used in a BPM context, the mapper provides:

  • Source model selection (from process context)

  • Target model selection

  • Field mapping with drag-and-drop

  • Integration with process variables

Technical Details

ValueMapper Entity

Field Type Description

name

String (unique)

Mapper name

script

Large String

Generated Groovy script

scriptMeta

Large String

JSON metadata for the React builder

targetField

String

Target model name

sourceField

String

Source model name

The React builder communicates with the server through URL parameters:

mapper/?id={{_id}}&model=com.axelor.studio.db.ValueMapper&resultField=script&resultMetaField=scriptMeta&targetField=targetField&sourceField=sourceField

Backend services:

  • ValueMapperController.execute() — Executes the generated script on a specified record

  • ValueMapperService — Core mapper execution logic