Eskalationsstufen

Die Eskalationskette eines Teams ist eine geordnete Liste von Stufen (Tiers). Stufe 1 wird zuerst alarmiert; Bereitschaft in einer Stufe hat, wen die Schedules der Stufe gerade in Schicht haben. Jede Stufe legt fest, ob und wann der Incident zur nächsten Stufe weiterwandert und wie oft die Stufe vorher erneut alarmiert wird. Wiederholungen der ganzen Kette stehen am Team (Team ändern).

AuthentifizierungAnkerlink kopieren

Basis-IM-Zugriff: eine IM-berechtigte Rolle oder ein organisationsweiter API-Token, und Incident Management für die Organisation aktiviert. Die Kette lesen darf jeder mit diesem Zugriff. Jedes Schreiben braucht die Team-Schreibhürde: Organisationsrolle admin, oder Team-Admin dieses Teams. Ein API-Token läuft mit der Rolle des Users, der ihn erstellt hat, also kommt nur ein Token durch, den ein Organisations-Admin erstellt hat.

StufenfelderAnkerlink kopieren

Eskalationskette lesenAnkerlink kopieren

GET /api/im/teams/:id/escalations

Liefert alle Stufen in Reihenfolge, jede mit ihren Schedules, Rotationsgruppen und Mitgliedern, dazu die Eskalationseinstellungen des Teams.

Beispiel (cURL)Ankerlink kopieren

curl -X GET "$BASE_URL/api/im/teams/3/escalations" \
  -H "Authorization: Bearer $TOKEN"

Antwort (Response)Ankerlink kopieren

200 OK

{
  "tiers": [
    {
      "id": 21,
      "tierOrder": 1,
      "autoEscalationEnabled": true,
      "autoEscalationAfterMinutes": 5,
      "autoEscalationStopMode": "acknowledged",
      "autoEscalationSeverities": null,
      "autoEscalationTimeFilters": [],
      "repeats": 0,
      "repeatsAfterMinutes": null,
      "repeatsStopMode": "acknowledged",
      "schedules": [
        {
          "id": 7,
          "displayName": "Primary On-Call",
          "timezone": "Europe/Berlin",
          "effectiveFrom": null,
          "effectiveUntil": null,
          "weeklySchedules": [],
          "rotationMode": "explicit",
          "rotationRepeats": "weekly",
          "customRepeatUnit": null,
          "customRepeatValue": null,
          "autoRotationSize": null,
          "roundRobinSize": 1,
          "startsOnDayOfWeek": 1,
          "startsOnDateOfMonth": null,
          "startsOnTime": "09:00",
          "rotations": [
            {
              "id": 12,
              "rotationOrder": 1,
              "members": [
                { "userId": "u_abc123", "userName": "Ada Lovelace", "userImage": null, "memberOrder": 1 }
              ]
            }
          ]
        }
      ]
    }
  ],
  "teamSettings": {
    "timezone": "Europe/Berlin",
    "escalationRepeats": 1,
    "escalationRepeatsAfterMinutes": 15,
    "escalationRepeatsStopMode": "acknowledged",
    "engagementReportEnabled": false,
    "engagementReportDayOfWeek": null,
    "engagementReportTime": null
  }
}

Die Schedule-Felder sind unter Rotationskadenz und Schedule aktualisieren erklärt.

Stufe hinzufügenAnkerlink kopieren

POST /api/im/teams/:id/tiers

Hängt eine Stufe ans Ende der Kette (tierOrder = höchste + 1), mit den Standardwerten aus der Tabelle oben. Im selben Schritt entsteht ein Schedule unter der Stufe: Name Tier N schedule, 24/7, rotationMode: "none", in der Zeitzone des Teams (oder UTC, wenn das Team keine hat), mit einer Rotationsgruppe, die die angegebenen Mitglieder in der angegebenen Reihenfolge enthält.

Anfrage (Request Body)Ankerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/teams/3/tiers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "memberUserIds": ["u_abc123", "u_def456"] }'

Antwort (Response)Ankerlink kopieren

200 OK: die Stufenfelder plus schedules mit dem einen neuen Schedule, in derselben Form wie in der Eskalationskette (Mitglieder ohne userImage).

{
  "id": 22,
  "tierOrder": 2,
  "autoEscalationEnabled": true,
  "autoEscalationAfterMinutes": 5,
  "autoEscalationStopMode": "acknowledged",
  "autoEscalationSeverities": null,
  "autoEscalationTimeFilters": [],
  "repeats": 0,
  "repeatsAfterMinutes": null,
  "repeatsStopMode": "acknowledged",
  "schedules": [
    {
      "id": 8,
      "displayName": "Tier 2 schedule",
      "timezone": "Europe/Berlin",
      "effectiveFrom": null,
      "effectiveUntil": null,
      "weeklySchedules": [],
      "rotationMode": "none",
      "rotationRepeats": null,
      "customRepeatUnit": null,
      "customRepeatValue": null,
      "autoRotationSize": null,
      "roundRobinSize": 1,
      "startsOnDayOfWeek": null,
      "startsOnDateOfMonth": null,
      "startsOnTime": null,
      "rotations": [
        {
          "id": 14,
          "rotationOrder": 1,
          "members": [
            { "userId": "u_abc123", "userName": "Ada Lovelace", "memberOrder": 1 },
            { "userId": "u_def456", "userName": "Bob Fixit", "memberOrder": 2 }
          ]
        }
      ]
    }
  ]
}

Stufe ändernAnkerlink kopieren

PATCH /api/im/teams/:id/tiers/:tierId

Jedes Feld aus der Tabelle Stufenfelder außer tierOrder ist optional und änderbar. Nur die im Body vorhandenen Felder ändern sich.

Beispiel (cURL)Ankerlink kopieren

curl -X PATCH "$BASE_URL/api/im/teams/3/tiers/21" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "autoEscalationAfterMinutes": 10,
    "autoEscalationSeverities": ["critical"],
    "autoEscalationTimeFilters": [{ "from": "18:00", "until": "08:00", "days": [1, 2, 3, 4, 5] }]
  }'

Antwort (Response)Ankerlink kopieren

200 OK: die Stufenfelder nach der Änderung (ohne schedules).

Stufe löschenAnkerlink kopieren

DELETE /api/im/teams/:id/tiers/:tierId

Löscht die Stufe samt ihren Schedules, Rotationsgruppen und Schichten. Die übrigen Stufen behalten ihre tierOrder; wer Stufe 2 von 3 löscht, behält die Positionen 1 und 3. Mit Neu ordnen schließt du die Lücke, falls du fortlaufende Nummern brauchst.

Beispiel (cURL)Ankerlink kopieren

curl -X DELETE "$BASE_URL/api/im/teams/3/tiers/22" \
  -H "Authorization: Bearer $TOKEN"

Antwort (Response)Ankerlink kopieren

200 OK

{ "success": true }

Stufen neu ordnenAnkerlink kopieren

POST /api/im/teams/:id/tiers/reorder

Nummeriert die Kette in der gesendeten Reihenfolge auf 1..n um.

Anfrage (Request Body)Ankerlink kopieren

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/teams/3/tiers/reorder" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tierIds": [22, 21] }'

Antwort (Response)Ankerlink kopieren

200 OK

{ "tiers": [{ "id": 22, "tierOrder": 1 }, { "id": 21, "tierOrder": 2 }] }

Schedule zu einer Stufe hinzufügenAnkerlink kopieren

POST /api/im/teams/:id/tiers/:tierId/schedules

Legt einen weiteren Schedule unter einer Stufe an, etwa einen Follow-the-Sun-Schedule in einer anderen Zeitzone, mit Kadenz und Rotationsgruppen in einem Aufruf. Bereitschaft in einer Stufe hat, wen irgendeiner ihrer Schedules gerade in Schicht hat.

Anfrage (Request Body)Ankerlink kopieren

Dazu die Kadenzfelder aus Rotationskadenz. Weggelassene Kadenzfelder stehen auf rotationMode: "none", roundRobinSize: 1, alles andere null. Die resultierende Kadenz wird als Ganzes validiert.

Beispiel (cURL)Ankerlink kopieren

curl -X POST "$BASE_URL/api/im/teams/3/tiers/21/schedules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "APAC Follow-the-Sun",
    "timezone": "Asia/Singapore",
    "weeklySchedules": [{ "from": "09:00", "until": "18:00", "days": [1, 2, 3, 4, 5] }],
    "rotationMode": "explicit",
    "rotationRepeats": "weekly",
    "startsOnDayOfWeek": 1,
    "startsOnTime": "09:00",
    "rotations": [{ "members": ["u_abc123"] }, { "members": ["u_def456"] }]
  }'

Antwort (Response)Ankerlink kopieren

200 OK: der neue Schedule in derselben Form wie in der Eskalationskette (Mitglieder ohne userImage).

Häufige FehlerAnkerlink kopieren

• 401 Unauthorized (unauthorized) wenn du nicht authentifiziert bist
• 403 Forbidden (imAccessDenied) bei einem kunden-gescopten Token, oder wenn deine Session keine IM-berechtigte Rolle hat
• 403 Forbidden (imNotEnabled) wenn Incident Management für die Organisation nicht aktiviert ist
• 403 Forbidden (imTeamWriteDenied) bei jedem Schreiben, wenn du weder Organisations-Admin noch Team-Admin dieses Teams bist
• 404 Not Found (imTeamNotFound) wenn das Team nicht existiert oder zu einer anderen Organisation gehört
• 404 Not Found (imEscalationTierNotFound) wenn :tierId keine Stufe dieses Teams ist
• 404 Not Found (imTeamMemberNotFound) wenn eine User-ID in memberUserIds oder rotations kein Mitglied dieses Teams ist
• 400 Bad Request (invalidRequestBody) wenn eine Pfad-ID keine positive Ganzzahl ist, memberUserIds fehlt, leer ist oder eine leere ID enthält, tierIds fehlt, leer ist oder nicht aus verschiedenen positiven Ganzzahlen besteht, name oder timezone fehlt oder ungültig ist, effectiveFrom/effectiveUntil kein gültiger Zeitstempel ist, oder rotations fehlerhaft ist
• 422 Unprocessable Entity (imTierReorderMismatch) wenn tierIds nicht genau die Stufen-IDs dieses Teams enthält
• 422 Unprocessable Entity (imInvalidRequestBody) wenn autoEscalationEnabled kein Boolean ist
• 422 Unprocessable Entity (imInvalidNumber) wenn autoEscalationAfterMinutes, repeats oder repeatsAfterMinutes keine Ganzzahl ab 0 ist, oder eine Kadenzzahl keine Ganzzahl ab 1
• 422 Unprocessable Entity (imInvalidStopMode) wenn ein Stop-Modus nicht acknowledged oder resolved ist
• 422 Unprocessable Entity (imInvalidSeverities) wenn autoEscalationSeverities weder null noch eine Liste aus critical, warning, minor ist
• 422 Unprocessable Entity (imInvalidTimeFilter) wenn eine Fensterliste kein Array ist, mehr als 50 Einträge hat, oder ein Eintrag kein Objekt ist oder kein days-Array hat
• 422 Unprocessable Entity (imInvalidTimeOfDay) wenn from/until eines Fensters oder startsOnTime nicht "HH:mm" ist
• 422 Unprocessable Entity (imInvalidDayOfWeek) wenn ein Fenstertag oder startsOnDayOfWeek nicht 1 bis 7 ist
• 422 Unprocessable Entity (imInvalidRotationMode) wenn rotationMode nicht none, auto oder explicit ist
• 422 Unprocessable Entity (imInvalidRotation) wenn die Kadenz nicht zusammenpasst, eine Liste mehr als 200 Mitglieder oder 50 Rotationsgruppen hat, oder eine User-ID in einer Liste doppelt vorkommt
• 409 Conflict (imTierOrderConflict) wenn zwei Stufen im selben Moment angelegt wurden; erneut versuchen