Skip to content

Data Mapping

Overview

Data mapping in Martini lets you transform and move data between workflow nodes and service steps using mapping lines and custom expressions. This feature provides complete control over how information flows through your logic, whether you're copying simple values, performing calculations, or formatting data for specific outputs.

Data mapping is a foundational skill required for effective Martini development. Understanding how to manipulate and transform data is essential for building workflows and services - you'll use these concepts in virtually every workflow or service you create. Mastering data mapping early will accelerate your ability to build complex integrations and business logic in Martini.

What You Will Learn

In this guide, you'll learn:

  • Understanding what properties are in Martini and how they store data
  • How to access the Data Mapper Panel in workflows and services
  • What the Data Mapper Panel looks like and its key components
  • How to create property mappings using visual map lines
  • How to build custom transformation logic with set expressions
  • Troubleshooting common data mapping issues and errors

When To Use This

Use data mapping when you need to:

  • Connect external data to your workflow or service - Take information from APIs, databases, or other systems and structure it for use in your automation
  • Share data between workflow nodes and/or service steps - Create properties that pass information from one part of your automation to another
  • Transform data formats between different workflow nodes and service steps or external systems
  • Calculate new values from existing properties using custom logic
  • Copy information from inputs to outputs without modification
  • Format data for specific API requirements or display purposes
  • Combine multiple properties into single formatted outputs
  • Set static values like configuration parameters or API keys

Prerequisites

Before starting this guide, ensure you have:

Depending on what you're working with, be familiar with their basic concepts:

Understanding Properties In Data Mapping

Properties are the fundamental building blocks of data manipulation. These are named containers that store information as it moves through your automation.

Properties Key Terms

Understanding these core concepts will help you work effectively with data mapping:

Term Definition Example
Property A named container that holds data in your workflow - think of it like a labeled box that stores information; similar to variables in programming languages. customerName holding "John Smith"
Input Property Data that comes into your workflow node/service step from inputs or previous nodes/steps firstName received from a form
Output Property Data that your workflow node/service step creates or modifies, which then flows to the next node/step fullName created by combining first and last names
Property Type The kind of data a property contains (text, number, date, etc.) age as an Integer, email as String
Nested Property Properties within data models customer.address.street where customer contains address, which contains street
Property Value The actual data stored inside a property The value "john@email.com" stored in the email property

Property Benefits and Use Cases

Properties solve the fundamental challenge of data management in automated workflows:

  • Standardized data structure ensures consistent information handling across workflow nodes and service steps
  • Type safety prevents data corruption and provides clear expectations for each value
  • Reusability allows the same data to be referenced multiple times throughout the workflow
  • Debugging support makes it easy to track data values and identify transformation issues

Working with the Data Mapper Panel

The Data Mapper Panel is your visual control center for data transformation, showing all available properties and enabling you to create new ones through an intuitive interface. This panel appears consistently across workflow nodes and service steps.

Opening the Data Mapper Panel

The process for accessing the Data Mapper Panel varies depending on whether you're working with workflows or services:

From Workflows

  1. Add a node to your workflow
  2. Click the expand icon on your Node to open the Data Mapper Panel
  3. The panel appears in the lower half of the Workflow Designer

Expected result: The Data Mapper Panel opens showing your current workflow properties with input sources on the left and transformation targets on the right.

From Services

  1. Add a step to your service
  2. Select your added step
  3. Click the Open Mapper option in the Service Editor Toolbar, or double click on the step
  4. The panel appears on the lower half of the Service Editor

Understanding Data Mapper Panel Layout

The Data Mapper Panel has two different layouts depending on the type of workflow node or service step you're working with:

Simple Mapper Layout

Used for nodes/steps that focus purely on data transformation within your workflow or service. This layout shows:

  • Left Panel (Input): Source properties available for mapping
  • Right Panel (Output): Target properties where you can send data
1
2
3
4
5
                    /*** Simple Mapper Layout **/              
|  Source Properties  |  Mapping Lines  |  Target Properties  |
|---------------------|-----------------|---------------------|
|    [sourceInput1]   |     ------->    |   [targetOutput1]   |
|    [sourceInput2]   |     ------->    |   [targetOutput2]   |

Used by:

Double Mapper Layout

Used for nodes/steps that interact with other Martini components or configured resources. This layout provides separate input and output mapping sections:

1
2
3
4
5
            /*** Input Mapper **/                    /*** Output Mapper **/
|  Source Input |Map Lines|Target Input|  |  Source Output |Map Lines|Target Output |
|---------------|---------|------------|  |----------------|---------|--------------|
| [srcInput1]   | ------> |[nodeInput1]|  | [nodeOutput1]  | ------> |[targetOut1]  |
| [srcInput2]   | ------> |[nodeInput2]|  | [nodeOutput2]  | ------> |[targetOut2]  |
Used by:

Double Mapper Sections:

  • Input Mapper (Left): Map workflow/service properties into the node/step's required inputs
  • Output Mapper (Right): Map the node/step's results back to workflow/service properties

The layout remains consistent across applicable workflow nodes and service steps. Only the specific properties shown in each panel change based on the node/step type. To see specific properties and detailed mapping examples for each node or step, visit their individual documentation pages listed in the Double Mapper Layout - Used by section.

Input Mapper (Left)

The Input Mapper appears on the left side of the Data Mapper Panel. This section serves two main purposes:

  • For processing nodes/steps: Map existing workflow or service properties into your node/step so it can process that data
  • For triggers: Access trigger input properties (such as webhook payloads or API responses) to transform their values using set expressions or map them to other workflow/service properties.

Note for triggers: Some trigger input properties must be selected first from the Properties tab of the trigger configuration before they appear here. See Accessing and Using Trigger Properties for details.

The Input Mapper is further divided into three panels:

1
2
3
4
5
        /*** Input Mapper (Left) **/              
|  Source Input |Mapping Lines|Target Input|
|---------------|-------------|------------|
|  [srcInput1]  |  ------->   |[targetIn1] |
|  [srcInput2]  |  ------->   |[targetIn2] |
Term Definition
Source Input Panel Left side showing existing properties you can use as data sources. These properties come from the current workflow/service inputs, previous nodes/steps, or external sources like webhooks and API calls.
Target Input Panel Right side showing a node/step's input properties you can map values to. Mapping values here is important to ensure the node/step processes your data.
Map Lines Visual connections showing which source input maps to target output property

Examples of how target inputs vary by node type:

  • Invoke Service Node: Target inputs are the input parameters required by the service being called
  • Database Node: Target inputs are the query parameters needed for the database operation
Output Mapper (Right)

The Output Mapper is at the right of the Data Mapper Panel.

It is further divided into three panels:

1
2
3
4
5
        /*** Output Mapper (Right) **/              
|  Source Output |Mapping Lines|  Target Output |
|----------------|-------------|----------------|
|  [srcOutput1]  |  ------->   |[targetOutput1] |
|  [srcOutput2]  |  ------->   |[targetOutput2] |
Term Definition
Source Output Panel Left side showing properties that the current node/step produces after processing its input values. You can map these to workflow/service outputs or pass them to subsequent nodes/steps.
Target Output Panel Right side showing workflow/service output properties where you can send the processed data. These properties become available to other parts of your logic. You can map values from these to other properties in your workflow/service or directly to your workflow/service output.
Map Lines Visual connections showing which source output maps to which target output property

Data Mapper Panel Controls and Features

The Data Mapper Panel provides these controls for managing your data transformations:

Control Location What It Does
Declare Property Simple Mapper: Right panel (Output)
Double Mapper: Output Mapper		 Add a new property to your workflow/service
Delete Simple Mapper: Right panel (Output)
Double Mapper: Output Mapper		 Remove properties (only those created in the current node/step)
Collapse All Simple Mapper: Both panels
Double Mapper: Both Input and Output Mappers		 Hide nested properties for cleaner view
Expand All Simple Mapper: Both panels
Double Mapper: Both Input and Output Mappers		 Show all nested properties and their structure
Find Simple Mapper: Both panels
Double Mapper: Both Input and Output Mappers		 Quickly locate specific properties by name
Toggle Comments Simple Mapper: Both panels
Double Mapper: Both Input and Output Mappers		 Show or hide comments added to properties for better workflow/service understanding

Working with Map Lines

Map lines are visual connections that copy data directly from source properties to target properties. This is the most common and efficient method for basic data transformation.

How to Create Map Lines

  1. Open the Data Mapper Panel.
  2. Find your source property in the Source Input Panel or Source Output Panel (left sides of each section)
  3. Click and drag from the source property to your target in the Target Input Panel or Target Output Panel (right sides of each section)
  4. Release to create the map line connection

Expected result: A visual line connects your source to target property, and the target property will receive the source value when the workflow/service runs.

Map Lines Key Terms

Term Definition
Source Property The input property providing data for the mapping
Target Property The output property receiving data from the mapping

Creating Properties with Automatic Mapping

There are several convenient ways to create new properties while simultaneously setting up their mappings:

Drag and Drop Method

  • Drag to empty space: Drag from an input property to empty space in the output mapper/panel to automatically create a new property with the same name

Right-Click Context Menu

Right-click any property to access these shortcuts:

  • Declare Property and Map: Creates a new property in the current panel and immediately maps the selected property to it

  • Add Property and Map:

    • From input properties: Adds a new property to the workflow/service's output properties and maps to it

    • From output properties: Adds a new property to the workflow/service's input properties and maps from it

    • A dialog appears asking you to enter a name for the new property

    • Enter the desired name in the dialog and click Add property and map

These methods save time by combining property creation and mapping in a single action, making development more efficient.

Example

Let's map an employee's full name to a display field:

  1. You have employeeFullName with value "Jane Doe" in your input
  2. Drag employeeFullName to displayName in the output mapper/panel
  3. When your workflow/service runs, displayName becomes "Jane Doe"

How It Works

Map lines execute in a specific order when your workflow/service runs:

Default Execution Order: Map lines run in the order you created the properties.

Removing Map Lines

  • Right-click the map line and select Delete
  • Keyboard shortcuts:
  • Windows/Linux: Select the line and press Delete
  • macOS: Select the line and press Backspace

Automatic Data Type Conversion

Martini handles data type conversion automatically, so you don't need to worry about matching property types when creating map lines. The system intelligently converts between different data types as needed.

Examples of automatic conversion:

  • String to Number: "123" automatically becomes 123
  • Number to Date: Timestamp values convert to proper Date objects

This flexibility means you can focus on your workflow/service logic rather than worrying about data type compatibility between properties.

Why It Matters

Map lines provide the simplest way to move data between workflow nodes or service steps. They're perfect for straightforward value copying without any transformation logic.

Best Practices

  • Use map lines for simple value copying - they're more efficient than set expressions for direct assignments
  • Trust automatic type conversion - Martini handles most data type mismatches seamlessly

Assigning Dynamic Values to Properties with Set Expressions

Set expressions let you manually assign a plain text value or an expression to be evaluated. Use them for transformations, calculations, or setting static values.

Creating Set Expressions

  1. Open the Data Mapper Panel
  2. Right-click a target property in the Data Mapper Panel and select Set Expression, or simply double-click the property
  3. Choose your language: Plain Text for static text or a scripting language like Groovy, JavaScript, Shell Script (Linux/macOS), or Batch (Windows) for dynamic expressions
  4. Write your expression in the editor
  5. Click Apply to save

Expected result: Your property will either calculate a dynamic value (for code expressions) or assign the exact text you entered (for plain text expressions) when the workflow/service runs.

Example: Static Text

Set an API key property for third-party services, databases, or authentication:

  1. Create an apiKey string property in the output mapper/panel
  2. Double-click it to open the Set Expression dialog
  3. Select Plain Text as the language
  4. Enter your value:
1
sk-1234567890abcdef

Expected result: The apiKey property always contains "sk-1234567890abcdef" when the workflow/service runs, ready for use in API calls.

Example: Dynamic Calculation

Combine and format user data from existing properties:

  1. First, create firstName and lastName string properties in the output mapper/panel and assign values to them
  2. Create a fullName string property in the output mapper/panel
  3. Double-click the fullName property to open the Set Expression dialog
  4. Select Groovy as the language
  5. Enter this code:
1
firstName + " " + lastName.toUpperCase()

Expected result: The fullName property contains the combined name with the last name in uppercase (e.g., "John SMITH") when the workflow/service runs.

How It Works

Set expressions execute during workflow/service runtime just like map lines:

Plain Text expressions:

  • Treated as literal string values
  • Perfect for static configuration or fixed messages

Code-based expressions:

  • Evaluated when the workflow/service runs
  • Support properties, calculations, and complex logic

Working with Nested Properties

Access nested properties in Models using dot notation:

1
2
3
4
5
6
7
8
// Access nested properties
myModel.nestedProperty

// Work with arrays
myModel.arrayProperty[0]

// Combine nested data
"${myModel.firstName} (${myModel.email})"

Why It Matters

Set expressions give you the power to create dynamic, calculated values without leaving your workflow/service. They're perfect when simple mapping isn't enough and you need custom logic or formatting.

Best Practices

  • Keep expressions simple - complex logic should be moved to separate script nodes/script steps or new workflows/services
  • Handle null values explicitly to prevent runtime errors: 
    1
    firstName != null ? firstName : 'Unknown'
  • Use meaningful variable names in complex expressions for better readability

Common Data Mapping Error Solutions

Problem Detection Cause Fix Affected Versions
Map line not working Property not updated in workflow/service Type mismatch between properties Verify source and target property types match All versions
Set expression error Runtime exception during execution Syntax error in code Check expression syntax and property references All versions
Property not available Missing in Data Mapper Panel view Property not declared or out of scope Declare property or check workflow/service scope All versions
Null reference error NullPointerException: Cannot invoke method on null object Referenced property contains no data Add null checks: property != null ? property.method() : 'default' All versions
Property resolution error MissingPropertyException: No such property Property name doesn't exist in scope Check spelling and verify property is available in current context All versions

Helpful Resources