Martini Workflows Map Node

Overview

Map Nodes are essential components in Martini workflows for setting and managing property values. They provide a streamlined approach to declare new properties and assign values using either map lines or set expressions within your workflow automation.

Map Nodes in workflows function similarly to Map Steps in services, allowing you to transform and manipulate data as it flows through your workflow automation sequence.

When to Use This

Use Map Nodes when you need to:

• Assign received values to new properties within the workflow
• Transform data between workflow steps
• Set static values or calculated results
• Combine multiple inputs into a single output
• Format data before sending it to external services

Prerequisites

• Martini Designer
• Create a Martini Package
• Create a Workflow
• Basic understanding of how to use Workflow Designer

Adding Map Nodes to Workflows

Getting Started

To add a Map Node to your workflow:

1. Navigate to your Martini Package and open your workflow
2. Click the Add Node button in the toolbar on the top left of the editor
3. Select Map from the available node types
4. Drag the Map Node to your desired position in the workflow
5. Connect it to other nodes using workflow edges

Expected result: A Map Node appears in your workflow where you can configure property mappings and transformations.

Properties

Understanding these fundamental concepts will help you work effectively with Map Nodes:

Core Concepts

Term	Definition	Example
Property	A named container that holds data in your workflow - think of it like a labeled box that stores information	customerName holding "John Smith"
Input Property	Data that comes into your Map Node from workflow inputs or previous nodes	firstName received from a form
Output Property	Data that your Map Node creates or modifies, which then flows to the next workflow step	fullName created by combining first and last names
Property Type	The kind of data a property contains (text, number, date, etc.)	age as a number, email as text
Nested Property	Properties within 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

Why Properties Matter

Properties are the building blocks of workflow data. Just like variables in programming, they let you:

• Store information temporarily as it moves through your workflow
• Pass data between different workflow steps
• Transform information from one format to another
• Reference data by name throughout your automation

Think of properties as the "ingredients" in your workflow recipe - you need to know what you have available and what you want to create to build effective automations.

Map Panel

The Map Panel is your control center for data transformation. It shows all available properties at the current point in your workflow and lets you create new ones.

Getting Started

1. Click the expand icon on your Map Node to open the Map Panel
2. The panel appears in the lower half of the Workflow Designer
3. You'll see two main areas: Input (left) and Output (right)

Expected result: The Map Panel opens showing your current workflow properties.

Key Terms

Term	Definition
Input Panel	Left side showing existing properties you can use as sources
Output Panel	Right side where you create new properties or update existing ones
Map Lines	Visual connections showing which input maps to which output
Set Expression	Custom code that calculates a property's value

Configuration Properties

The Map Panel provides these controls:

Control	Location	What It Does
Declare Property	Output panel	Add a new property
Delete	Output panel	Delete properties (only those created in this node)
Collapse All	Both panels	Hide nested properties
Expand All	Both panels	Show nested properties
Find	Both panels	Find specific properties quickly
Toggle Comments	Both panels	Show or hide comments added to properties for better workflow understanding

How It Works

The Map Panel operates as a visual data transformer:

1. Input properties appear on the left - these come from your workflow's inputs or previous nodes
2. Output properties appear on the right - these are either workflow outputs or new properties you create
3. Map lines connect inputs to outputs, showing data flow
4. Set expressions let you write custom logic instead of simple mapping

When your workflow runs, the Map Node processes all mappings and expressions in priority order, then passes the results to the next node.

Why It Matters

The Map Panel gives you complete control over your data transformation without writing complex code. You can see exactly what data you have, where it's going, and how it's being changed - all in one visual interface.

Best Practices

• Use descriptive property names that clearly indicate their purpose (e.g., customerDisplayName instead of name)
• Test with sample data to verify your setup works as expected before deploying
• Group related properties logically to make your workflow easier to understand

Map Lines

Map lines create direct connections between input and output properties, copying values from source to destination.

Getting Started

1. Open the Map Panel by clicking the expand icon on your Map Node
2. Find your source property in the Input Panel (left side)
3. Click and drag from the source property to your target in the Output Panel (right side)
4. Release to create the map line

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

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 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's output properties and maps to it
  • From output properties: Adds a new property to the workflow'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 your workflow 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 panel
3. When your workflow runs, displayName becomes "Jane Doe"

How It Works

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

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

Custom Execution Order and Priorities

You can control the exact sequence using priorities to ensure correct execution, especially in Map Nodes with more than 10 mapping lines:

• Lower numbers run first (priority 1 executes before priority 2)
• Setting priorities: Select a map line, then modify the priority in the Configuration view on the right

Why priorities matter: In workflows with many mappings (10+), execution order issues can go unnoticed during development but cause runtime errors in production.

Example: E-commerce shipping calculation where each map line depends on values calculated by previous map lines:

Priority 1: baseShippingRate = itemWeight * zoneMultiplier
Priority 2: tierDiscount = baseShippingRate * discountPercentage  (depends on Priority 1 result)
Priority 3: finalShippingCost = baseShippingRate - tierDiscount   (depends on Priority 1 & 2 results)

Without priorities: Calculations might execute randomly, causing tierDiscount to use null/incorrect baseShippingRate values.

With priorities: Each calculation ensures it uses properly computed values from previous steps, preventing silent calculation errors in complex workflows.

This is critical for financial calculations, data validation workflows, and report generation where incorrect execution order leads to wrong results.

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 logic rather than worrying about data type compatibility between properties.

Why It Matters

Map lines provide the simplest way to move data between workflow 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

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.

Getting Started

1. Open the Map Panel from the Map Node
2. Right-click an output property in the Map 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 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 panel
2. Double-click it to open the Set Expression dialog
3. Select Plain Text as the language
4. Enter your value:

sk-1234567890abcdef

Expected result: The apiKey property always contains "sk-1234567890abcdef" when the workflow 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 panel and assign values to them
2. Create a fullName string property in the output panel
3. Double-click the fullName property to open the Set Expression dialog
4. Select Groovy as the language
5. Enter this code:

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 runs.

How It Works

Set expressions execute during workflow 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 runs
• Support properties, calculations, and complex logic

Working with Nested Properties

Access nested properties in Models using dot notation:

// 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. 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 or workflows.
• Handle null values explicitly to prevent runtime errors:

  firstName != null ? firstName : 'Unknown'
  

• Use meaningful variable names in complex expressions for better readability

Troubleshooting

Problem	Detection	Cause	Fix	Affected Versions
Map line not working	Property not updated in workflow	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 Map Panel view	Property not declared or out of scope	Declare property or check workflow scope	All versions
Priority conflicts	Unexpected execution order	Multiple items with same priority	Assign unique priorities or verify execution sequence	All versions

Helpful Resources

• Martini Workflows - Complete workflow documentation
• Parts of a Workflow
• Workflow Designer - Visual workflow editor guide
• All Workflow Nodes - Complete node reference
• Map Steps in Services - Similar functionality in services
• Workflow Concepts - Fundamental workflow principles
• Community Q&A: Martini Community
  Have a Question? Post or search it here.