Data Mapper in HTTP Actions

Build complex JSON payloads directly in the HTTP Action body editor using Data Mapper syntax.

Overview

Data Mapper is a YAML-based transformation language for constructing and manipulating JSON payloads. Within Data Mapper, you can also use DSL expressions for string manipulation, type conversion, and computed values.

1 # Data Mapper with DSL expressions
2 ticket_number: number.display_value.$TRIM()
3 total: "$INTEGER(quantity) * $INTEGER(price)"

When to Use Data Mapper

Use Data Mapper when you need to:

Build dynamic arrays of objects from input data
Create nested JSON structures with computed fields
Transform data before sending (filter, map, sort)
Include conditional fields based on input values

Stick with Mustache for simple variable substitution where the JSON structure is static.

Quick Start

Mustache (Before)

1 {
2   "user": "{{user_email}}",
3   "message": "{{message_text}}"
4 }

Data Mapper (After)

1 user: user_email
2 message: message_text.$TRIM()

Both produce the same output for simple cases. Data Mapper is useful when you need array manipulation or conditional logic.

Building Complex Payloads

Example 1: Create a List of Objects

Scenario: Send a bulk update request with multiple items.

Input Data:

1 {
2   "items": [
3     {"id": "001", "name": "Item A", "quantity": 5},
4     {"id": "002", "name": "Item B", "quantity": 3}
5   ]
6 }

Data Mapper:

1 updates:
2   MAP():
3     items: items
4     converter:
5       item_id: item.id
6       item_name: item.name.$UPPERCASE()
7       qty: item.quantity

Output:

1 {
2   "updates": [
3     {"item_id": "001", "item_name": "ITEM A", "qty": 5},
4     {"item_id": "002", "item_name": "ITEM B", "qty": 3}
5   ]
6 }

Example 2: Conditional Fields

Scenario: Include a field only when a condition is met.

Input Data:

1 {
2   "priority": "high",
3   "description": "Server is down"
4 }

Data Mapper:

1 ticket:
2   description: description
3   urgency:
4     CONDITIONAL():
5       condition: priority == 'high'
6       on_pass: "'urgent'"
7       on_fail: "'normal'"

Output:

1 {
2   "ticket": {
3     "description": "Server is down",
4     "urgency": "urgent"
5   }
6 }

Example 3: Flatten Nested Data

Scenario: Extract values from a nested API response.

Input Data (ServiceNow-style):

1 {
2   "number": {"display_value": "INC12345", "value": "INC12345"},
3   "state": {"display_value": "Open", "value": "1"},
4   "assigned_to": {"display_value": "John Doe", "value": "user123"}
5 }

Data Mapper:

1 ticket_number: number.display_value
2 status: state.display_value
3 assignee: assigned_to.display_value.$TRIM()

Output:

1 {
2   "ticket_number": "INC12345",
3   "status": "Open",
4   "assignee": "John Doe"
5 }

Example 4: Filter and Transform Arrays

Scenario: Send only high-priority items to an API.

Input Data:

1 {
2   "tasks": [
3     {"name": "Task 1", "priority": 1},
4     {"name": "Task 2", "priority": 3},
5     {"name": "Task 3", "priority": 1}
6   ]
7 }

Data Mapper:

1 high_priority_tasks:
2   FILTER():
3     items: tasks
4     condition: item.priority == 1

Output:

1 {
2   "high_priority_tasks": [
3     {"name": "Task 1", "priority": 1},
4     {"name": "Task 3", "priority": 1}
5   ]
6 }

Example 5: Build Request from 2D Array

Scenario: Transform a Snowflake/SQL response into structured JSON.

Input Data:

1 {
2   "columns": ["id", "name", "email"],
3   "rows": [
4     ["001", "Alice", "alice@example.com"],
5     ["002", "Bob", "bob@example.com"]
6   ]
7 }

Data Mapper:

1 users:
2   MAP():
3     items: rows
4     converter:
5       MERGE():
6         FLATTEN():
7           - "item.$MAP((x, i) => {columns[i]: x})"

Output:

1 {
2   "users": [
3     {"id": "001", "name": "Alice", "email": "alice@example.com"},
4     {"id": "002", "name": "Bob", "email": "bob@example.com"}
5   ]
6 }

Common Operators Reference

Operator	Purpose	Example
`MAP()`	Transform each item in array	`MAP(): { items: list, converter: ... }`
`FILTER()`	Keep items matching condition	`FILTER(): { items: list, condition: item.active }`
`CONDITIONAL()`	If/else logic	`CONDITIONAL(): { condition: x > 5, on_pass: ..., on_fail: ... }`
`MERGE()`	Combine multiple objects	`MERGE(): [obj1, obj2]`
`FLATTEN()`	Flatten nested arrays	`FLATTEN(): [arr1, arr2]`
`CONCAT()`	Join strings	`CONCAT(): { items: [a, b], separator: ", " }`
`LOOKUP()`	Map values	`LOOKUP(): { key: status, mapping: {"1": "Open"} }`

String Functions

Apply directly to field values:

1 # Trim whitespace
2 name: user_name.$TRIM()
3 
4 # Convert to uppercase
5 code: product_code.$UPPERCASE()
6 
7 # Convert to lowercase  
8 email: user_email.$LOWERCASE()
9 
10 # Parse as integer
11 count: "$INTEGER(quantity_string)"

Troubleshooting

Tip: Test with hardcoded values first, then add Data Mapper transformations one at a time.

Syntax Errors

Data Mapper uses YAML. Watch for:

Indentation: Use consistent spaces (not tabs)
Quotes: String literals need single quotes inside: "'literal string'"
Colons in values: Wrap in quotes if value contains :

Wrong:

1 message: Hello: World

Correct:

1 message: "'Hello: World'"

Empty Arrays

If MAP() or FILTER() returns empty, check:

The items path is correct
Input data actually contains the expected array
Filter condition isn’t too restrictive

Debugging

Test your API with hardcoded values first
Add one Data Mapper transformation at a time
Check the Response tab to see actual output

Migration from Mustache

Mustache	Data Mapper Equivalent
`{{variable}}`	`variable`
`{{{array}}}` (stringified)	`array` (as actual array)

Key difference: Data Mapper preserves types. Arrays stay as arrays, numbers stay as numbers. No need for $STRINGIFY_JSON() workarounds.

1	# Data Mapper with DSL expressions
2	ticket_number: number.display_value.$TRIM()
3	total: "$INTEGER(quantity) * $INTEGER(price)"

1	{
2	"user": "{{user_email}}",
3	"message": "{{message_text}}"
4	}

1	{
2	"items": [
3	{"id": "001", "name": "Item A", "quantity": 5},
4	{"id": "002", "name": "Item B", "quantity": 3}
5	]
6	}

1	updates:
2	MAP():
3	items: items
4	converter:
5	item_id: item.id
6	item_name: item.name.$UPPERCASE()
7	qty: item.quantity

1	{
2	"updates": [
3	{"item_id": "001", "item_name": "ITEM A", "qty": 5},
4	{"item_id": "002", "item_name": "ITEM B", "qty": 3}
5	]
6	}

1	ticket:
2	description: description
3	urgency:
4	CONDITIONAL():
5	condition: priority == 'high'
6	on_pass: "'urgent'"
7	on_fail: "'normal'"

1	{
2	"ticket": {
3	"description": "Server is down",
4	"urgency": "urgent"
5	}
6	}

1	{
2	"number": {"display_value": "INC12345", "value": "INC12345"},
3	"state": {"display_value": "Open", "value": "1"},
4	"assigned_to": {"display_value": "John Doe", "value": "user123"}
5	}

1	ticket_number: number.display_value
2	status: state.display_value
3	assignee: assigned_to.display_value.$TRIM()

1	{
2	"ticket_number": "INC12345",
3	"status": "Open",
4	"assignee": "John Doe"
5	}

1	{
2	"tasks": [
3	{"name": "Task 1", "priority": 1},
4	{"name": "Task 2", "priority": 3},
5	{"name": "Task 3", "priority": 1}
6	]
7	}

1	high_priority_tasks:
2	FILTER():
3	items: tasks
4	condition: item.priority == 1

1	{
2	"high_priority_tasks": [
3	{"name": "Task 1", "priority": 1},
4	{"name": "Task 3", "priority": 1}
5	]
6	}

1	{
2	"columns": ["id", "name", "email"],
3	"rows": [
4	["001", "Alice", "alice@example.com"],
5	["002", "Bob", "bob@example.com"]
6	]
7	}

1	users:
2	MAP():
3	items: rows
4	converter:
5	MERGE():
6	FLATTEN():
7	- "item.$MAP((x, i) => {columns[i]: x})"

1	{
2	"users": [
3	{"id": "001", "name": "Alice", "email": "alice@example.com"},
4	{"id": "002", "name": "Bob", "email": "bob@example.com"}
5	]
6	}

1	# Trim whitespace
2	name: user_name.$TRIM()
3
4	# Convert to uppercase
5	code: product_code.$UPPERCASE()
6
7	# Convert to lowercase
8	email: user_email.$LOWERCASE()
9
10	# Parse as integer
11	count: "$INTEGER(quantity_string)"