Mapper

Reshape data between one skill and the next.

Mapper transforms and maps data from source fields to target fields. Use it for renaming fields, reshaping structures, converting types, or supplying defaults before data reaches a downstream skill.

It exists because the shape one system returns is rarely the shape the next one wants. Rather than teaching every skill to speak every format, put the translation between them where you can see it.

How it works

• Input resolution — resolves the previous skill's output via $input. Vault secrets are available through $secret.

• Processing — works through the mappings list in order. For each mapping it extracts a value from a source path, applies defaultValue if the path is missing, converts the value to the declared type (string, number, any, date), and writes it to the target field.

• Execution — blocking. Waits for all mappings to complete.

• Response — on success, a data object holding every mapped target field. On failure, data: null and an error message.

Worked example

Configuration:

{
  "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:

{
  "data": {
    "firstName": "John",
    "age": 32,
    "signupDate": "2025-07-27T10:00:00.000Z"
  },
  "statusCode": 200
}

When a source path is missing and no default is set:

{
  "data": null,
  "statusCode": 422,
  "error": "Source path user.age not found and no defaultValue provided"
}

A missing source path fails the whole mapping, not just that field — data comes back null. If a field is genuinely optional, give it a defaultValue. That one decision is the difference between a resilient mapper and a workflow that stops the first time an upstream system omits a field.

Configuration reference

Field	Type	Required	Description
mappings	array<object>	✅	Source-to-target mappings. Each: target, type (string | number | any | date), source, and optional defaultValue.
name	string	—	Display name for the skill.
description	string	—	Description for documentation.

Defining data mappings to standardize field names and types

Output

The output port (mapperOutput) always conforms to:

Field	Type	Always	Description
data	any | null	—	The object holding all mapped target fields.
statusCode	number	✅	HTTP-style status; 200 on success.
error	string | null	—	Error message on failure.

Errors

Status	Cause
400	Invalid mapping syntax, or an empty target field.
422	A source path was not found in the input and no defaultValue was provided.

Security

• Secrets from $secret are never written to the output unless you explicitly map them.

• Exclude or rename fields carrying sensitive data to prevent unintentional exposure — a mapper is exactly where PII quietly acquires a new name and travels somewhere it shouldn't.

• Log redaction policies apply to sensitive mapping values.

Testing in isolation

• Path — /skill-runtime/workflows/nodes/Mapper/execute

• Method — POST

• Body:

{
  "config": { "name": "Mapper Skill", "description": "For better workflow structure" },
  "input":  { "userId": 12345, "status": "active" }
}

---

To add this skill to an agent, see Adding a Skill to the Agent.