Transformation Rule configuration

A Transformation Rule maps an incoming webhook payload into Unit Oncall's normalized alert format. It can be created independently of other resources.

Fields

Field	Type	Required	Default	Notes
`name`	string	Yes	—	Rule name. Cannot be empty.
`description`	string	No	`""`	Free-text description.
`is_active`	boolean	Yes	—	Whether the rule is active. Send this value explicitly (`true` to enable). If omitted, the rule is treated as inactive (`false`).
`mappings`	object	Yes	`{}`	Mapping definitions per target field. Target-field keys: `fingerprint`, `title`, `message`, `severity`, `timestamp`, `labels`, `tags` — each of these values is a field mapping (see below). The object also accepts the string-valued array options `array_delimiter` / `array_trim_chars` (see Array options), which sit alongside the target-field entries.

Field mapping

Each entry in mappings is an object describing how to extract that target field from the incoming payload:

Sub-field	Required	Value	Notes
`type`	Yes	`jsonpath`, `format`, or `static`	The extraction method.
`path`	When `type` is `jsonpath`	JSONPath string	Path into the incoming payload.
`format`	When `type` is `format`	format string	Template that combines other values.
`value`	When `type` is `static`	fixed value	A constant value. For `labels` / `tags` this must be a string or an array of strings, and every element must satisfy the tag character rule (only `A-Z` `a-z` `0-9` and `-` `_` `.` `:` `/`, at most 200 characters) — see Tags and labels.
`mapping`	No	key–value map	Translates an extracted value to another value.
`default`	No	fallback value	Used when extraction yields nothing.

fingerprint, title, and severity are recommended for reliable alerts, though they are not strictly enforced.

Character rule for labels / tags. A type: static value is configuration you author, so it must use the supported tag character set and the rule is enforced when you save the Transformation Rule. Values produced by type: jsonpath or type: format come from the incoming payload and are not checked — whatever your monitoring tool sends is stored on the alert as sent. Such a value simply cannot be used for routing or bundling, so the alert follows your default routing. See Tags and labels.

⚠️ Define tags explicitly if you rely on bundling. When mappings has no tags entry, Unit Oncall falls back to the incoming payload's own top-level tags field and stores whatever it finds there, unchanged. That is convenient for getting started, but bundling groups alerts whose tag sets are exactly equal (Bundle Settings), so a payload that carries a per-alert value — a hostname, an instance or pod name, a request ID — makes the alert match no Bundle Settings entry. Such an alert is not given a Bundle of its own: it joins the Schedule's shared Default Bundle with every other unmatched alert, and while that Bundle is open the alerts joining it raise no new notification (only an escalation to critical still pages). Passing the payload through can therefore silence alerts, not just fail to group them. Map tags to the stable dimensions you group on (with jsonpath, format, static, or a mapping translation) rather than passing the payload through. The full payload is still kept on the alert for investigation.

⚠️ Map timestamp (the detection time) whenever your source provides it. When timestamp is absent, Unit Oncall falls back to the time the webhook was received. Under delivery retries or network reordering, the order of state transitions for the same fingerprint (e.g. warning → critical → info) may be misjudged, so an alert's current state can settle on the wrong severity or a resolved alert may appear unresolved. Map your source's detection time (e.g. Prometheus/Grafana startsAt, Datadog $LAST_UPDATED). Accepted formats: RFC3339 string or epoch seconds/milliseconds.

Array options

mappings also accepts two options that sit alongside the target-field entries (they are keys of mappings, not of an individual field mapping). They control how a delimited string is turned into the labels / tags arrays.

Key in `mappings`	Type	Required	Default	Notes
`array_delimiter`	string	No	`,`	Characters that separate array elements in a delimited string. Every character in the value is treated as a delimiter, so `,;` splits on both commas and semicolons.
`array_trim_chars`	string	No	`""`	Characters stripped from the start and end of each element — for example `'` turns `'a','b'` into `a`, `b`, and `'"` strips both quote styles. Applies only to `labels` / `tags` read straight from the incoming payload (that is, when `mappings` defines no entry for them); values produced by a `labels` / `tags` mapping are not trimmed. Empty means no trimming.

Splitting only happens when the value is a delimited string: a labels / tags value that already arrives as a JSON array — a real array, or a string such as ["a","b"] — is read as an array. One exception to array_delimiter: a format-type mapping for labels / tags always splits its result on commas.

{
  "mappings": {
    "fingerprint": { "type": "jsonpath", "path": "$.alert_id" },
    "array_delimiter": ",;",
    "array_trim_chars": "'\""
  }
}