Incident Definitions

Configure when incidents are created and how operators are notified

Incident definitions determine when incidents are triggered based on status definitions, how operators are notified, and what actions are available for response. Each incident can have different behaviors for warning, error, and recovery states.

When to Use

• Alert routing: Send critical issues to Slack, OpsGenie, or webhooks
• Automatic recovery: Trigger scripts automatically when incidents occur
• Operator workflows: Offer relevant actions when operators acknowledge incidents
• Severity classification: Assign SEV levels for proper escalation

Spec Fields

Field	Type	Required	Description
statusId	string	Yes	ID of the status definition that triggers this incident.
label	string	Yes	Display name for the incident.
labelTemplate	string	No	Dynamic label with mustache-style replacements (e.g., {{{robotName}}}).
warning	object	No	Configuration for warning state.
error	object	No	Configuration for error state.
ok	object	No	Configuration for recovery (status returns to OK).

State Configuration (warning/error/ok)

Field	Type	Description
notificationChannels	array	Channels to route alerts through.
autoActions	array	Action IDs to run automatically when triggered.
manualActions	array	Action IDs offered to operators as response options.
severity	string	Severity level: "SEV 0", "SEV 1", "SEV 2", "SEV 3". Not applicable for ok.

Notification Channels

Channel	Format	Description
App	"app"	InOrbit application notifications
Slack	"slack#channel-name"	Slack channel (include the #)
Google Chat	"googleChat"	Google Chat notifications
OpsGenie	"opsgenie"	OpsGenie integration
Webhook	"webhook"	Custom webhook endpoint

Examples

Basic Incident with Notifications

kind: IncidentDefinition
apiVersion: v0.1
metadata:
  id: "batteryLow"
  scope: account/<accountId>
spec:
  statusId: "batteryLevel"
  label: "Low Battery"
  warning:
    notificationChannels:
      - "app"
    severity: "SEV 2"
  error:
    notificationChannels:
      - "app"
      - "slack#alerts"
    severity: "SEV 1"

With Dynamic Label and Actions

kind: IncidentDefinition
apiVersion: v0.1
metadata:
  id: "navigationStuck"
  scope: account/<accountId>
spec:
  statusId: "unableToNavigate"
  label: "Navigation Stuck"
  labelTemplate: "Navigation stuck on {{{robotName}}} at {{{locationName}}}"
  warning:
    notificationChannels:
      - "app"
    manualActions:
      - "restart-navigation"
    severity: "SEV 2"
  error:
    notificationChannels:
      - "app"
      - "slack#operations"
      - "opsgenie"
    autoActions:
      - "stop-robot"
    manualActions:
      - "restart-navigation"
      - "return-to-dock"
    severity: "SEV 0"
  ok:
    notificationChannels:
      - "app"

Full Example with All Options

kind: IncidentDefinition
apiVersion: v0.1
metadata:
  id: "motorOverheat"
  scope: account/<accountId>
spec:
  statusId: "motorTemperature"
  label: "Motor Overheating"
  labelTemplate: "Motor overheating on {{{robotName}}}"
  warning:
    notificationChannels:
      - "app"
    autoActions: []
    manualActions:
      - "reduce-speed"
    severity: "SEV 2"
  error:
    notificationChannels:
      - "app"
      - "slack#critical-alerts"
      - "opsgenie"
    autoActions:
      - "emergency-stop"
    manualActions:
      - "reduce-speed"
      - "return-to-dock"
    severity: "SEV 0"
  ok:
    notificationChannels:
      - "app"
    autoActions: []
    manualActions: []

Template Variables

The labelTemplate field supports these variables:

Variable	Description
{{{robotName}}}	Robot display name
{{{robotId}}}	Robot ID
{{{locationName}}}	Current location name
{{{statusValue}}}	Current status value

Related Documentation

• Status Definitions — Define statuses that trigger incidents
• Action Definitions — Define actions for incident response