Alert Schemas

Alert Schemas are the contract between an Alert Producer, 1stLine, and an Alert Receiver.

An Alert Schema tells 1stLine how to parse incoming Alert Events, which fields can be used for Routing Conditions and Communication Conditions, how repeated Alert Events become one Alert Instance, and how acknowledgement, resolution, and incident lifecycle updates can be sent back to the receiver.

Open Alert Schemas to manage schemas. Open Create Alert Schema to create a schema from Library or from an alert payload.

What an Alert Schema controls

An Alert Schema has these main parts:

• Schema Token identifies the schema used by the Alert Producer Destination. This isn’t entirely a secret token because it can’t authorize any action except alert ingestion, but since the billing model is based on processed Alert Events, treat it carefully to avoid unexpected costs.
• Alert Producer Destination is the URL you place in the producer configuration so alerts enter 1stLine first. Replace the forwardTo placeholder with the real Alert Receiver URL or webhook, for example a Slack webhook.
• Default Forward To is the fallback Alert Receiver destination when the producer request does not include forwardTo.
• Proxy recurrent alerts controls whether repeated firing occurrences are forwarded to the Alert Receiver after they are deduplicated into the same Alert Instance. Default is false to follow the industry established standards.
• Patterns extract fields from incoming payloads using Schema Patterns. A pattern can also include ordered fallback attempts when the same field can appear in more than one place.
• Fields define the field contract used by routing, escalation, and action mapping. Almost never manually hardcode these fields. Instead, create patterns that will produce these fields after extraction.
• Fingerprint Fields decide which fields will build the hash for deduplication into Alert Instances. Alert Instances matching the same fingerprint increment Recurrences unless they match a Resolution Pattern. If your Alert Producer passes fingerprint in the payload, use it as the fingerprint. Otherwise, choose stable fields that are unique for your alerts.
• Resolution Proxy Config controls how resolution updates are forwarded. Options are none, source-only or 1stLine-generated-only, or both.
• Resolution Patterns set a pattern of incoming alert that will resolve an Alert Instance that produces the same fingerprint.
• Resolution Mapping maps fields into generated resolution messages.
• Acknowledgement Configuration configures acknowledgement links, whether unauthenticated guest acknowledgements are allowed, and acknowledgement message fields.
• Incident Lifecycle Mapping maps Incident lifecycle events into alert-side updates.
• Transformation Template reshapes the outbound payload before forwarding.
• AI Override Forward To is an optional destination used for AI assignment responses and terminal status updates.
• AI Escalation Mapping controls alert-side content for AI assignment updates, including the assignment details link.

The schema details page groups these settings into tabs: Schema Config, Acknowledgement, Resolution, Incident, Transformation, and AI Escalation.

Alert Producer Destination

Each schema details page shows Schema Token and Alert Producer Destination in the Ingestion panel.

The Alert Producer Destination is built from the proxy route, Schema Token, organization context, and an optional forwardTo receiver value:

.../{schema_token}?org_uid=...&forwardTo=<your-destination-webhook>

Use this value in the Alert Producer. If the value contains <your-destination-webhook>, replace it with the real Alert Receiver destination before testing.

If the producer request includes forwardTo, that destination is used. If it does not include forwardTo, 1stLine uses Default Forward To. If neither is available for normal Alert Producer traffic, the request is rejected because there is no Alert Receiver destination.

Default Forward To can also be used for Incident Lifecycle triggered messages when the original Alert Instance does not have its own forwardTo. More in Incident Lifecycle Mapping.

Creating schemas

1stLine supports two customer-facing creation paths.

Choose from Library lets you select a Library Schema and create a real Alert Schema from it. This is the fastest path when a matching schema already exists.

Create New Schema creates a schema from a real custom alert payload.

1. 1stLine creates a temporary one-time Schema Creation Token and forms a temporary Destination URL.
2. You configure your producer to send a real alert example to that Destination URL. Choose the most representative example to allow 1stLine to make the maximum number of automatically parsed fields.
3. 1stLine will wait for an incoming alert on that URL and once received will create the schema based on the example.

Caution

The Schema Creation Token is short-lived and works only one time. After sending the test alert, update the Alert Producer configuration with the real Alert Schema token instead of the creation token.

4. Study the parsed fields and think of additional ones you or 1stLine might need. For the proper escalation and alert instance configuration, 1stLine needs fields such as:

   • priority
   • summary or description
   • title or message
   • labels or tags

The simplest way to develop extraction patterns is to use the dedicated Schemas Creation AI Skill and 1stLine MCP server.

Additionally, we have a separate document explaining all Pattern Types with examples: Schema Patterns.

5. You can test your pattern extractions directly in 1stLine UI by clicking Test Pattern Extraction. There you can paste your example payload and see how the fields are extracted with the full explanation and trace.

Caution

Aborting the creation process before finishing will abort the Schema Creation Token. If a temporary schema has already been created, aborting from the details step deletes that schema.

Library Schemas

Library Schemas are reusable schema templates. A Library Schema can be global or organization-scoped.

When you choose a Library Schema, 1stLine creates a new Alert Schema in your organization. The new schema gets its own Schema Token and starts enabled.

You can also save a schema definition as an organization-scoped Library Schema when you want your team to reuse the same shape later.

Global Library Schemas are maintained by Burava and the community. Feel free to browse available Library Schemas and request or contribute new ones in our Library Schemas repository.

Fingerprint Fields

Fingerprint Fields identify repeated alerts for deduplication.

When Alert Events produce the same fingerprint, 1stLine updates the same Alert Instance instead of creating a new unrelated instance.

Fingerprint behavior follows this order:

1. If the incoming payload has a string fingerprint, 1stLine uses it.
2. If Fingerprint Fields are configured, 1stLine builds a hash from those fields.
3. If the payload has labels, 1stLine tries building a hash from sorted labels.
4. Otherwise, 1stLine builds a hash from the payload after removing common time fields such as timestamp, startsAt, and endsAt.

Choose stable fields that describe the actual alert condition, not fields that change on every send.

Recurrent Alert Proxying

Repeated firing alerts can do two separate things in 1stLine:

1. update the same Alert Instance by matching the same fingerprint
2. forward another message to the Alert Receiver

These are related, but they are not the same.

Proxy recurrent alerts controls the forwarding part.

• When Proxy recurrent alerts is off, repeated firing occurrences still update the same Alert Instance and increase Recurrences, but 1stLine suppresses forwarding of those repeated firing messages to the receiver.
• When Proxy recurrent alerts is on, repeated firing occurrences still update the same Alert Instance, and 1stLine also forwards each recurrence to the receiver.

Use this setting based on what the receiver should see:

• keep it off when the receiver should only get the first firing message and 1stLine should track later repeats internally
• turn it on when every repeated firing occurrence should also be forwarded downstream

Caution

Default configuration for proxy_recurrent_alerts is false to follow the industry established standards. If you want to mirror your alert producer setup, set it to true.

Resolution

The Resolution tab controls how 1stLine recognizes and forwards resolution updates.

Resolution Patterns detect source resolution events. When the incoming alert computes the same fingerprint and matches a Resolution Pattern, 1stLine marks the Alert Instance as resolved and stops active Escalation Assignments for that alert.

Resolution Proxy Config controls which resolution updates are forwarded to the receiver:

• All (Source & Generated) forwards both the source resolution alert and 1stLine generated message.
• Source Resolutions Only forwards the Alert Producer generated RESOLVED alert to the destination.
• 1stLine Generated Resolutions Only. 1stLine can generate a generic short resolution message and forward it to the same destination as the firing one was delivered to.
• None (No Resolutions) suppresses resolution forwarding.

Resolution Mapping maps fields into generated resolution notifications. Its UI labels include Title Field, Description/Message Field, Fallback Title Field, Status Field, Resolution Link Field, Key, and Value.

Initial firing alerts are still forwarded. Resolution Proxy Config controls whether your receiver gets resolution update messages.

Acknowledgement

The Acknowledgement tab controls acknowledgement links and acknowledgement messages.

Acknowledgement Link Field is the payload path where 1stLine injects the acknowledge link.

Unacknowledgement Link Field is the payload path where 1stLine injects the unacknowledge link.

Allow Guest Acknowledgement lets users acknowledge alerts without logging in by using a generated guest token. See Alert Actions for more information.

Acknowledgement Mapping maps alert fields into acknowledgement messages. Its UI labels include Title Field, Description/Message Field, Fallback Title Field, Status Field, Key, and Value.

Incident Lifecycle Mapping

The Incident tab contains Incident Lifecycle Mapping.

Incident Lifecycle Mapping can send alert-side updates when Incident lifecycle events happen. Supported triggers are:

• created
• reopened
• resolved
• closed
• priority_changed

Each trigger can map fields such as title, description, status, and incident link.

For each incident lifecycle change, you can either send the update notification only by enabling Send Alert, create a new Alert Instance by enabling Register Alert, or enable both.

For example, when the Priority of the incident is changed to P1 and Register Alert is enabled, 1stLine creates a new Alert Instance with mapped fields. If that Alert Instance matches Routing Rules, it can start an escalation flow for responders and prompt them to join the Incident.

Alert Instances created from Incident lifecycle changes with Register Alert enabled are counted towards your Alert Events limit.

All incident lifecycle triggered messages follow the same forwarding rules as firing alerts. If the original firing alert had forwardTo in the producer request, lifecycle updates go to the same destination. Otherwise, they follow the schema Default Forward To or stay unforwarded if no default is set.

Incident lifecycle overrides can use incident values and source alert values together.

Useful incident values include:

• incident.uid
• incident.link
• incident.alert_instance_uid
• incident.title
• incident.description
• incident.status
• incident.priority
• incident.event.type
• incident.event.actor_email
• incident.event.actor_name

See Incidents for more information about Incident Events, Incident Actions, and Incident Alert Instances.

Transformation

1stLine provides you with the powerful transformation engine that can reshape the original payload in two main ways:

1. Through overrides and injection configuration in Acknowledgement Mapping, Resolution Mapping, and Incident Lifecycle Mapping. The transformation engine resolves the pattern that was used to extract the configured field and applies the same formatting back to the mapped field.

For example, your alert labels are passed in payload as:

Labels:
- instance = prod-1
- team = payments
- priority = P1

If labels are extracted as dictionary with KeyPairRegex pattern, you can add additional entries as labels.__alert_resolve_link__ and your payload Labels will be transformed to:

Labels:
- instance = prod-1
- team = payments
- priority = P1
- __alert_resolve_link__ = https://1stline.burava.com/<link-to-resolve>

Additionally, you can use variable interpolation in overrides, for example:

attachments[0].text = Priority: ${priority:-unknown}, Maintainer: ${labels.team:-unassigned}

and the result will be:

attachments[0].text = Priority: P1, Maintainer: unassigned

2. Through the Transformation Template that can reshape the whole outbound payload before forwarding. See detailed explanation below.

Transformation Template

A Transformation Template is an optional JSON object that reshapes the outbound payload before proxy forwarding. Use it when the Alert Receiver expects a different payload shape than the Alert Producer sends or when you want to completely change the structure of the outbound payload.

The 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}.

Caution

Template Transformation happens before Acknowledgement, Resolution, and Incident Lifecycle mapping. If your configuration overrides or injects values into fields you indicated in Transformation Template, those mappings will override the values following their configuration.

Use Test transformation to preview the outbound payload. The result includes pattern extraction, template rendering, and simulated action-link overlays. If pattern extraction produces warnings, fix the extraction first and then test the template again.

Tip

By combining transformation template and a default_forward_to override, you can route your alerts to the different receiver or even another 1stLine schema achieving circular routing.

Mapping overrides and variables

Acknowledgement Mapping, Resolution Mapping, and Incident Lifecycle Mapping can also use variable interpolation inside override values.

For overrides, 1stLine supports:

• ${field}
• ${field:-fallback text}

That means overrides can provide visible fallback text when a value is missing.

Example:

attachments[0].text = Priority: ${priority:-unknown}

This is different from Transformation Template. In Transformation Template, only ${field} and ${field:-} are supported.

Schema Tokens

Schema Tokens identify which Alert Schema should process incoming producer traffic.

Schema Tokens are not a replacement for API Tokens. They are included in the Alert Producer Destination and can be visible to systems that send alerts.

Treat Schema Tokens carefully because traffic sent with a valid token can create processed Alert Events and usage. See Billing and Limits for more information.

Disabled schemas do not accept Schema Token traffic.

Default Forward To

Default Forward To is the fallback Alert Receiver destination used when an Alert Producer request does not include forwardTo.

Update Default Forward To when you want the schema to use a new default Alert Receiver destination.

If the producer request includes forwardTo, that destination is still used instead.

AI Escalation Mapping

The AI Escalation tab controls how AI assignment updates are sent back to the receiver.

Use AI Override Forward To when AI assignment responses and terminal status updates should go to a dedicated destination instead of the original producer forwardTo value or the schema Default Forward To.

Use AI Escalation Mapping when the receiver payload should include AI assignment details. Its UI labels include Enable AI escalation mapping, Title Field, Fallback Title Field, Message Field, and Assignment Link Field.

The Assignment Link Field is the payload path where 1stLine can inject the AI assignment details URL.

See Escalate to AI for the AI Escalation workflow.

MCP support

Alert Schemas are supported through dedicated MCP tools.

Schema tools:

• list_alert_schemas
• get_alert_schema
• update_alert_schema
• delete_alert_schema
• create_schema_creation_token
• create_alert_schema_from_payload
• create_alert_schema_from_library_schema
• test_alert_schema_patterns
• test_alert_schema_transformation_template

Library Schema tools:

• create_org_library_schema
• update_org_library_schema
• delete_org_library_schema
• list_global_library_schemas
• get_global_library_schema
• update_global_library_schema
• delete_global_library_schema
• list_org_library_schemas
• get_org_library_schema

MCP tools are org-scoped and require the configured organization context.

This page describes what the Alert Schema MCP tools do. For MCP client setup, authentication headers, and organization context configuration, see MCP Server.

Related pages

• Create Custom Schema
• Create Schema from Library Schema
• Writing Transformation Templates
• Getting Started
• Core Concepts
• Alert Flow
• Routing Rules
• Communication
• Incidents

GitHub and Slack are third-party brands. Burava does not own, represent, or speak for those brands.