Overview
Every incident created in Rootly is characterized by a structured set of properties. These properties define how an incident behaves, how it progresses through its lifecycle, how it interacts with workflows and automation, and how it appears in reporting and analytics. Incident properties serve several critical purposes:- Help characterize each incident (e.g.,
kind = normal) - Trigger workflow automations (e.g., Status Updated)
- Define conditional logic for workflow execution (e.g., Severity is SEV0)
- Enable filtering and segmentation of metrics
- Allow structured access through Liquid syntax
- Fixed Properties — system-defined and not customizable
- Configurable Properties — built-in but organization-customizable
- Custom Fields — fully defined and managed by your organization
Fixed Properties
Fixed properties are intentionally restricted to maintain lifecycle integrity, automation consistency, and reporting standardization across the Rootly platform.
Incident Kind
The Kind property determines the classification and structural behavior of an incident at the time it is created. It is immutable after declaration. Each kind controls workflow triggers, lifecycle expectations, and status page eligibility.| Kind | Description | Data Value |
|---|---|---|
| Incident | Standard production incidents declared via /rootly new. These represent real operational events requiring coordinated response. They trigger normal workflow execution and are eligible for publication on status pages (when not cancelled). | normal |
| Sub Incident | Child incidents created under a parent incident using /rootly sub. They inherit contextual linkage from the parent incident and are useful for tracking parallel workstreams or related issues within a broader event. Eligible for status page publication (when not cancelled). | normal_sub |
| Test Incident | Training or simulation incidents declared via /rootly test. They behave functionally like normal incidents but are excluded from status page publication and production metrics. Primarily used to test workflows, integrations, and team processes safely. | test |
| Sub Test Incident | Child incidents created under test incidents. Used exclusively for training and simulation. Not eligible for status page publication. | test_sub |
| Backfill Incident | Retroactively documented incidents created after resolution has already occurred. Backfill incidents are automatically created in a resolved state. Workflows triggered on Incident Created still execute, but active lifecycle stages such as Started or Mitigated are skipped. Eligible for status page publication (when not cancelled). | backfilled |
| Scheduled Maintenance | Planned maintenance windows declared via /rootly maintenance. These incidents follow a distinct maintenance lifecycle separate from normal incident statuses. Used to proactively communicate planned changes via status pages. | scheduled |
| Sub Scheduled Maintenance | Child incidents created under scheduled maintenance incidents. These follow the same maintenance lifecycle as their parent scheduled incident. | scheduled_sub |
Normal incidents default to in_triage status when the team setting “Incidents must start in the In-Triage status” is enabled. Otherwise, they default to started status upon creation.
Incident Status
The Status property defines the lifecycle stage of an incident and governs how it progresses from investigation through closure. Status transitions are validated to preserve chronological and logical integrity.Standard Incident Statuses
| Status | Description | Data Value |
|---|---|---|
| Triage | An investigative state used to determine whether an issue should escalate into an active incident. This allows teams to evaluate signals before formally beginning response. Timestamped at in_triage_at. | in_triage |
| Started | Marks the official activation of incident response. This is the primary active state during which coordination, mitigation, and communication occur. Timestamped at started_at. | started |
| Mitigated | Indicates that user-facing impact has been halted or reduced, but remediation, validation, or cleanup work may still be ongoing. Timestamped at mitigated_at, which must be after or equal to started_at. | mitigated |
| Resolved | Signifies the completion of active incident response. At this stage, service impact has ended and retrospective processes typically begin. Timestamped at resolved_at. | resolved |
| Closed | Optional terminal status (team-configurable) used to mark incidents as fully finalized after review. Requires the incident to already be in Resolved status. Timestamped at closed_at. | closed |
| Cancelled | Terminal status used for false positives or duplicate incidents. Cancelling prevents further lifecycle progression unless the incident is reopened. Timestamped at cancelled_at. | cancelled |
Terminal Statuses
Resolved, Closed, and Cancelled are considered terminal statuses. These statuses prevent further lifecycle progression unless the incident is explicitly reopened to Started, which restarts active response tracking.Status Transition Rules
Lifecycle Constraints
- Incidents in Triage or Cancelled cannot transition directly to Mitigated, Resolved, or Closed
- Closed can only be reached from Resolved
- Terminal statuses (Resolved, Closed, Cancelled) may be reopened to Started
Timestamp Validation Rules
Chronological IntegrityStatus timestamps are validated to preserve lifecycle order:
mitigated_at≥started_atresolved_at≥started_atclosed_at≥started_at
Sub-Statuses
When enabled via team configuration, statuses may contain sub-statuses to provide more granular tracking within a parent lifecycle stage. For example:- Started may include multiple Active sub-statuses (up to 8 per team)
- Resolved may include structured post-incident stages such as “Retrospective”
Scheduled Maintenance Statuses
Scheduled Maintenance incidents follow a separate lifecycle from standard incidents.| Status | Description | Data Value |
|---|---|---|
| Scheduled | Indicates that the maintenance window has been planned and formally created but has not yet begun. | scheduled |
| In Progress | Indicates that maintenance work is actively underway. | in_progress |
| Completed | Indicates that maintenance activities have concluded successfully. This is the default terminal state. | completed |
| Planning* | (Feature-flag dependent) Used while maintenance is being prepared but not yet scheduled. | planning |
| Verifying* | (Feature-flag dependent) Used when maintenance work is complete but final validation checks are in progress. | verifying |
| Cancelled* | (Feature-flag dependent) Used to cancel scheduled maintenance. Terminal state. | cancelled |
Configurable Properties
Configurable properties are built-in fields that organizations can customize to reflect their operational structure, severity model, and reporting taxonomy.| Property | Description |
|---|---|
| Environments | Characterizes incidents by environment (e.g., Development, Staging, Production). Commonly used to prioritize production-impacting incidents and to filter metrics and workflow conditions. |
| Severities | Defines impact levels (e.g., SEV0–SEV3). Drives escalation logic, workflow triggers, and reporting analysis. |
| Incident Types | Custom categorization distinct from Kind. Allows organizations to define taxonomy such as UI Bug, Infrastructure Failure, Security Event, etc. |
| Incident Roles | Defines structured responder roles (Incident Commander, Communications Lead, etc.) to coordinate responsibilities during response. |
| Teams | Assigns ownership and organizational routing responsibility to teams or groups. |
| Services | Identifies impacted infrastructure components. Used for service-level reporting and status page communication. |
| Functionalities | Identifies impacted product capabilities (e.g., login, checkout). Enables feature-level transparency. |
| Incident Causes | Categorizes root causes to support retrospective analysis and long-term reliability improvements. |
Property Order
The ordering of values within configurable properties determines how they appear in dropdown menus and forms. Ordering is global and affects all users. You can:- Drag and drop values manually
- Sort values alphabetically
Custom Fields
When built-in properties are insufficient to meet your organization’s needs, you can create Custom Fields to extend the incident schema. Custom Fields allow you to:- Capture structured or unstructured metadata
- Apply validation and defaults
- Power advanced workflow automation
- Reference values using Liquid syntax
- Enforce organization-specific incident taxonomy
Frequently Asked Questions
Can I change an incident's Kind after it's created?
Can I change an incident's Kind after it's created?
No. The Kind property is immutable after an incident is created. It determines the incident’s structural behavior, workflow triggers, and status page eligibility at creation time. If you need a different kind, you must create a new incident with the desired kind.For example, you cannot convert a Test Incident to a normal incident, or change a Scheduled Maintenance to a standard incident after creation.
What's the difference between Kind and Type?
What's the difference between Kind and Type?
Kind is a fixed, system-defined property that controls how an incident behaves structurally (e.g.,
normal, test, scheduled). It cannot be customized and determines workflow execution, lifecycle, and status page eligibility.Type (Incident Types) is a configurable property that allows organizations to define their own categorization taxonomy (e.g., “UI Bug”, “Infrastructure Failure”, “Security Event”). Types are fully customizable and can be used for filtering, reporting, and workflow conditions, but they don’t affect the fundamental behavior of the incident.Think of Kind as “what kind of incident is this structurally?” and Type as “what category does this incident fall into for our organization?”Can I reopen a resolved or closed incident?
Can I reopen a resolved or closed incident?
Yes. Terminal statuses (Resolved, Closed, Cancelled) can be reopened to Started status. This restarts active response tracking and allows the incident to progress through its lifecycle again.Reopening is useful when:
- An incident recurs after resolution
- Additional investigation reveals the original resolution was incomplete
- A cancelled incident turns out to be a real issue
Why can't I transition directly from Triage to Resolved?
Why can't I transition directly from Triage to Resolved?
Status transitions are validated to preserve logical lifecycle progression. Incidents in Triage or Cancelled cannot skip directly to Mitigated, Resolved, or Closed because these statuses require the incident to have been actively responded to (i.e., in Started status first).To resolve an incident that’s in Triage, you must first transition it to Started, then proceed through Mitigated (optional) to Resolved.
What happens if I set a timestamp that violates chronological order?
What happens if I set a timestamp that violates chronological order?
Rootly validates timestamp relationships to maintain chronological integrity. If you attempt to set
mitigated_at, resolved_at, or closed_at to a time before started_at, the system will reject the change and display a validation error.Timestamps must follow this order:started_at≤mitigated_at≤resolved_at≤closed_at
Can I delete or modify fixed properties like Kind or Status?
Can I delete or modify fixed properties like Kind or Status?
No. Fixed properties (Kind and Status) are system-defined and cannot be modified, deleted, or customized. They exist to ensure consistency across the platform and maintain the integrity of workflow automation and reporting.If you need different categorization options, use Configurable Properties (like Incident Types) or Custom Fields, which can be fully customized to meet your organization’s needs.
What's the difference between Resolved and Closed status?
What's the difference between Resolved and Closed status?
Resolved indicates that active incident response has completed and service impact has ended. At this stage, retrospective processes typically begin.Closed (when enabled via team configuration) is an optional terminal status used to mark incidents as fully finalized after review. It requires the incident to already be in Resolved status and provides a clear distinction between incidents that are resolved but still under review versus incidents that are completely closed.Not all teams use the Closed status. If it’s not enabled, Resolved serves as the terminal status.
Do test incidents trigger workflows?
Do test incidents trigger workflows?
Yes. Test incidents trigger workflows just like normal incidents, allowing you to test workflow automation safely without affecting production metrics or status pages. However, test incidents are excluded from status page publication and production reporting.This makes test incidents ideal for:
- Validating workflow configurations
- Training team members on incident response
- Testing integrations without production impact
How do sub-statuses affect workflow execution?
How do sub-statuses affect workflow execution?
Sub-statuses provide granular tracking within parent statuses (like Started or Resolved) but don’t change the fundamental status-based workflow triggers. Workflows that trigger on “Status Updated” will still fire when the parent status changes, regardless of sub-status transitions.However, you can use sub-statuses in workflow run conditions to create more specific automation logic. For example, a workflow could run only when an incident is in Started status with a specific Active sub-status.Sub-statuses are particularly useful for enforcing sequential workflows within a status.
Can I use custom fields in workflow conditions?
Can I use custom fields in workflow conditions?
Yes. Custom fields can be referenced in workflow run conditions and Liquid templates, allowing you to create sophisticated automation based on organization-specific data.Custom fields are accessible via Liquid syntax:This enables workflows to react to custom field values, trigger actions based on custom data, and include custom field information in notifications and integrations.
Why are backfill incidents automatically resolved?
Why are backfill incidents automatically resolved?
Backfill incidents are designed to document incidents retroactively—after they’ve already been resolved. Since the incident has already concluded, they are created directly in a Resolved state.Workflows triggered on Incident Created still execute for backfill incidents, but active lifecycle stages (like Started or Mitigated) are skipped because the incident is already resolved.
Can scheduled maintenance incidents use standard incident statuses?
Can scheduled maintenance incidents use standard incident statuses?
No. Scheduled Maintenance incidents follow a separate lifecycle with dedicated statuses (Scheduled, In Progress, Completed, etc.). They cannot use standard incident statuses like Started, Mitigated, or Resolved.This separation exists because maintenance windows have different lifecycle requirements than unplanned incidents.
What happens if I change the order of configurable property values?
What happens if I change the order of configurable property values?
Property ordering is global, meaning changes affect all users immediately. When you reorder values (e.g., Severities or Environments), the new order appears in:
- Dropdown menus when creating or editing incidents
- Form fields across the platform
- Any interface where that property is displayed
Need help or have a question?Contact us anytime at support@rootly.com, use the
/rootly support Slack command, or visit Getting Help to start a chat.