Writing Transformation Templates

Use Transformation Template when the Alert Receiver needs a different payload shape than the Alert Producer sends.

This is useful when the producer payload is good enough for 1stLine, but the receiver expects different field names, nesting, or message text.

Before you write a template

Confirm that Patterns already extract the values you need.

Transformation Templates render from the extracted context. If a field is missing from the pattern test result, the template cannot reliably use it.

See Schema Patterns before writing the template if extraction is not ready.

Template rules

A Transformation Template must be a JSON object at the root.

String values can use placeholders:

{
  "title": "${title}",
  "message": "${description:-}",
  "status": "${status}"
}

${field} inserts a field value. If the field is missing, the rendered value becomes [no-value].

${field:-} inserts a field value, or an empty string when the field is missing.

Nested paths and array indexes are supported, for example ${attachments[0].title}.

Only empty fallback syntax is supported. Use ${field:-}, not ${field:-fallback text}.

That rule is specific to Transformation Template.

If you are editing override values in Acknowledgement Mapping, Resolution Mapping, or Incident Lifecycle Mapping, those override values can use ${field:-fallback text}. See Alert Schemas for that separate behavior.

Example

Assume Schema Patterns extract this context:

{
  "title": "CPU high",
  "description": "CPU is above threshold",
  "priority": "P1"
}

You can write this Transformation Template:

{
  "summary": "${title}",
  "details": "${description:-}",
  "severity": "${priority}"
}

The outbound payload becomes:

{
  "summary": "CPU high",
  "details": "CPU is above threshold",
  "severity": "P1"
}

Write and test the template

1. Open Alert Schemas.
2. Select your schema with View.
3. Open Transformation.
4. Paste a realistic payload into Example Payload JSON.
5. Write the template in Transformation Template JSON.
6. Click Test transformation.
7. Review Transformation Result.
8. Confirm the Transformation Template section change.

Transformation Result is a preview of the outbound payload after template rendering and simulated action-link overlays.

If Transformation Result contains [no-value], the placeholder does not have a value in the extracted context. Fix the placeholder or update Patterns.

If you see Pattern extraction warnings, test Patterns directly before changing the template.

Action links

Acknowledgement, unacknowledgement, and resolution links are applied after the template is rendered.

If Acknowledgement Link Field, Unacknowledgement Link Field, or Resolution Link Field points to a field in the transformed payload, 1stLine can inject the generated link into that field.

For example, this template prepares fields where the receiver can show action links:

{
  "summary": "${title}",
  "details": "${description:-}",
  "links": {
    "ack": "",
    "resolve": ""
  }
}

Then set:

Acknowledgement Link Field = links.ack
Resolution Link Field = links.resolve

After rendering, the receiver payload can include:

{
  "summary": "CPU high",
  "details": "CPU is above threshold",
  "links": {
    "ack": "https://...",
    "resolve": "https://..."
  }
}

Use fields the receiver actually displays. If the receiver hides links.ack or links.resolve, responders may not see the action links even though 1stLine added them.

See MCP Server if you want to test or manage transformation work through MCP tools.

Keep templates small

Prefer a template that reshapes the payload for the receiver, not one that tries to encode every possible alert detail.

Keep the important responder-facing values easy to find: title, message, severity or priority, source, and action links.

See Alerts&Schemas Troubleshooting if the result does not match the expected payload.