Mapper Node
Purpose and How the Node Works
The Mapper Node is used to transform and map data from source fields to target fields within a workflow. It's especially useful for renaming fields, reshaping data structures, converting types, or assigning default values before passing data to downstream nodes.
Input Resolution: The node resolves input from the previous node's output, accessible via the $input variable. Vault secrets can be referenced using $secret.
Request/Processing: The node processes a list of mappings defined in its configuration. For each mapping, it extracts a value from a specified source path, optionally applies a default value if the source path is missing, converts the value to a defined type (string, number, any, or date), and then writes the value to the target field in the output object.
Execution Model: The node operates in a blocking manner, waiting for all mappings to complete.
Response Handling: On success, the node returns a data object containing all the mapped target fields. On failure, it returns a data: null with an error message.
Configuration Schema
The Mapper Node's behavior is defined by its mappings array.
Field
Type
Required
Description
mappings
Array of objects
✅
Defines a list of source-to-target mappings. Each mapping object includes: target, type ("string", "number", "any", or "date"), source (string), and an optional defaultValue (string).
name
string
No
Optional display name for the node.
description
string
No
Optional description for documentation.
Output Schema
The node's output port (mapperOutput) will always conform to the following schema.
data
any | null
No
The output object with all mapped target fields.
statusCode
number
✅
HTTP-style status code for the result, with 200 on success.
error
string | null
No
An error message for failures.
Examples
Success Example
Configuration
JSON
{
"mappings": [
{ "target": "firstName", "type": "string", "source": "user.first_name" },
{ "target": "age", "type": "number", "source": "user.age" },
{ "target": "signupDate", "type": "date", "source": "user.created_at" }
]
}
Output
JSON
{
"data": {
"firstName": "John",
"age": 32,
"signupDate": "2025-07-27T10:00:00.000Z"
},
"statusCode": 200
}
Failure Example
Configuration
JSON
{
"mappings": [
{ "target": "age", "type": "number", "source": "user.age" }
]
}
Input (assuming user.age is not present)
Output
JSON
{
"data": null,
"statusCode": 422,
"error": "Source path user.age not found and no defaultValue provided"
}
Single-Node Test API
For testing a node in isolation (e.g., via the UI "Test" button or a dedicated API), the following endpoint is used:
Path: /skill-runtime/workflows/nodes/Mapper/execute
Method: POST
Purpose: Execute one node in isolation.
Request Body:
JSON
{
"config": {
"name": "Mapper Node",
"description": "For better workflow structure"
},
"input": {
"userId": 12345,
"status": "active"
}
}
Error Handling
400 Bad Request: Occurs with invalid mapping syntax or an empty target field.
422 Unprocessable Entity: Occurs when a source path is not found in the input, and no default value is provided.
Security Notes
Secrets from $secret are never written to the output unless they are explicitly mapped.
Fields containing sensitive data should be excluded or renamed to prevent unintentional exposure.
Log redaction policies apply to sensitive mapping values.
Last updated