Kontrollparameter (X-S4 Parameter) (Statuszuordnung, Anreicherung, Filterung) – SIGNL4 Deutsch

Der SIGNL4-Webhook kann mehr als nur Ereignisse empfangen, um Signls auszulösen. Er kann zum Beispiel auch zuvor ausgelöste Signls aktualisieren (Statusänderung), um beide Systeme synchron zu halten. Die benachrichtigten Benutzer können dann sofort sehen, ob ein Vorfall im Drittsystem bereits wieder behoben wurde.
Darüber hinaus ist es auch möglich, zusätzliche Vorfallseigenschaften/-inhalte hinzuzufügen oder zu steuern, wie das Team benachrichtigt werden soll.

Übersicht der Kontrollparameter

Kontrollparameter haben einen eigenen, vordefinierten Namen und können an beliebiger Stelle in der übermittelten Ereignis-Nutzlast (z. B. JSON) enthalten sein. Die folgende Tabelle gibt einen Überblick über alle verfügbaren Kontrollparameter.

Parameter	Type of control	Description
X-S4-Service	Incident data and routing	Assigns the triggered Signl to the category have the name of this parameter value. SIGNL4 categories can augment the incident or define who is responsible, etc. Will be overwritten if category is assigned in distribution rule.
X-S4-Location	Incident data	Used to define where the incident is located. Value is a string containing latitude and longitude separated by a coma.
X-S4-AlertingScenario	Alerting workflow	Possible values include “single_ack” (acknowledgement from only one person on duty is required) and “multi_ack” (acknowledgement from all people on duty is required). If “emergency” is specified, the triggered Signl gets assigned to the emergency category and always all people in the team are notified (regardless of their duty status).
X-S4-Filtering	Event filtering	A bool value of true or false to apply event filtering for this event, or not. If set to true, the event will only trigger a Signl if it matches the setup keyword filtering in a Signl category of the target team (i.e. it is whitelisted or not blacklisted). Otherwise it may trigger a Signl assigned to the Default category, in case no specific category keyword setup matches.
X-S4-ExternalID	Status mapping	Used to correlate multiple events sent to the webhook to one and the same incident. Type is string and value should be a unique incident id.
X-S4-Status	Status mapping	Used to update created incidents (Signls) based on the incident ID (X-S4-ExternalID). Value represents the name of the status the corresponding Signl should transition to. Possible values are “New”, “Acknowledged”, “Resolved”.

Status-Zuordnung

Um den Status eines zuvor ausgelösten Signals zu aktualisieren, muss bei der Übermittlung des ersten Ereignisses zunächst eine eindeutige Ereignis-ID (X-S4 ExternalID) angegeben werden. Diese ID muss für nachfolgende Ereignisse, die dann nur den Status ändern sollen, gleich sein.
Der neue Status, den ein zuvor erstelltes Signl zugewiesen bekommen soll, wird mit dem Parameter "X-S4-Status" festgelegt. Nachfolgend ein Beispiel für den Ablauf:

1 - Erstes Ereignis, das ein Signal auslöst

{
  "Title": "Critical production failure",
  "Message": "Check line machine C immediately",
  "Severity": "High",
  "Business Details": {
      "Impact": "Major",
      "Scope": "Unlimited"
  },
  "X-S4-ExternalID": "e3b0c44",
  "X-S4-Status": "New"
}

X-S4-Status ist bei der ersten Auslösung des Signals optional.

2 - Der Vorfall wird im System des Dritt-Systems bestätigt, das Signl ist zu bestätigen

{
  "Title": "Critical production failure",
  "Message": "Check line machine C immediately",
  "Severity": "High",
  "Business Details": {
      "Impact": "Major",
      "Scope": "Unlimited"
 },
 "X-S4-ExternalID": "e3b0c44",
 "X-S4-Status": "Acknowledged"
}

Wenn der Status eines zuvor erstellten Signls aktualisiert werden soll, sind alle Nicht-Kontrollparameter oder JSON-Objekte optional.

3 - Vorfall ist im Dritt-System geschlossen, Signl ist zu schließen

{
  "Title": "Critical production failure",
  "Message": "Check line machine C immediately",
  "Severity": "High",
  "Business Details": {
      "Impact": "Major",
      "Scope": "Unlimited"
 },
 "X-S4-ExternalID": "e3b0c44",
 "X-S4-Status": "Resolved"
}

Wenn der Status eines zuvor erstellten Signls aktualisiert werden soll, sind alle Nicht-Kontrollparameter oder JSON-Objekte optional.

Statuszuordnung über URL-Abfrageparameter

Das oben beschriebene Status-Mapping setzt voraus, dass Sie die Kontrolle über den Event-Payload / Body im 3rd-Party-System haben, um die SIGNL4-Kontrollparameter einzuspeisen. Wenn dies nicht der Fall ist und Sie mit einem vordefinierten Schema arbeiten müssen, können Sie das Mapping über die unten aufgeführten URL-Abfrageparameter instruieren. Sie geben an, welche Parameter im Body Werte enthalten, die für den zuvor beschriebenen Status-Mapping-Mechanismus erforderlich sind.

Query parameter	Description
ExtIdParam	Name of the parameter in the posted event body that holds a unique incident id required for status mapping (equivalent for ‘X-S4-ExternalID’)
ExtStatusParam	Name of the parameter in the posted event body that holds a status which is mapped to the SIGNL4 status of “New”, “Acknowledged” or “Closed”.
NewStatus	Value that the body parameter which name equals the value of “ExtStatusParam” must have, to trigger a new Signl. If any other status value than behind “NewStatus”, “AckStatus” or “ResolvedStatus” is received, the event is discarded.
AckStatus	Value that the body parameter which name equals the value of “ExtStatusParam” must have, to transition the corresponding Signl’s status to acknowledged.
ResolvedStatus	Value that the body parameter which name equals the value of “ExtStatusParam” must have, to transition the corresponding Signl’s status to closed.

Der gleiche Statusabbildungsfluss unter Verwendung von URL-Abfrageparametern zur Beschreibung der Kontrollparameter sieht wie folgt aus:

1 - Erstes Ereignis, das ein Signl auslöst

POST https://connect.signl4.com/webhook/g93sdfm2843?ExtIdParam=Id&
ExtStatusParam=Status_t&NewStatus=DOWN&AckStatus=PENDING&
ResolvedStatus=UP HTTP/1.1
Host: connect.signl4.com
Connection: keep-alive
Content-Length: 362
Pragma: no-cache
Cache-Control: no-cache
Content-Type: application/json

{
  "Title": "Critical production failure",
  "Message": "Check line machine C immediately",
  "Severity": "High",
  "Business Details": {
      "Impact": "Major",
      "Scope": "Unlimited"
 },
 "Id": "e3b0c44",
 "Status_t": "DOWN"
}

2 - Der Vorfall wird im Dritt-System bestätigt, das Signl ist zu bestätigen

POST https://connect.signl4.com/webhook/g93sdfm2843?ExtIdParam=Id&
ExtStatusParam=Status_t&NewStatus=DOWN&AckStatus=PENDING&
ResolvedStatus=UP HTTP/1.1
Host: connect.signl4.com
Connection: keep-alive
Content-Length: 362
Pragma: no-cache
Cache-Control: no-cache
Content-Type: application/json

{
  "Title": "Critical production failure",
  "Message": "Check line machine C immediately",
  "Severity": "High",
  "Business Details": {
      "Impact": "Major",
      "Scope": "Unlimited"
 },
 "Id": "e3b0c44",
 "Status_t": "PENDING"
}

3 - Vorfall ist im Dritt-System geschlossen, Signl ist zu schließen

POST https://connect.signl4.com/webhook/g93sdfm2843?ExtIdParam=Id&
ExtStatusParam=Status_t&NewStatus=DOWN&AckStatus=PENDING&
ResolvedStatus=UP HTTP/1.1
Host: connect.signl4.com
Connection: keep-alive
Content-Length: 362
Pragma: no-cache
Cache-Control: no-cache
Content-Type: application/json

{
  "Title": "Critical production failure",
  "Message": "Check line machine C immediately",
  "Severity": "High",
  "Business Details": {
      "Impact": "Major",
      "Scope": "Unlimited"
 },
 "Id": "e3b0c44",
 "Status_t": "UP"
}

Verworfene Zwischenereignisse

Es würde nichts passieren und vor allem würde kein neues Signal ausgelöst werden, wenn das System eines Drittanbieters "zwischenzeitliche" Aktualisierungsereignisse wie das unten stehende auslöst und diese beiden Bedingungen erfüllt sind:

alle drei Status (neu, bestätigt und abgeschlossen) werden in den Abfrageparametern angegeben/zugewiesen
jedes Ereignis enthält immer noch dieselbe externe Kennung im deklarierten/gemappten Körperparameter

POST https://connect.signl4.com/webhook/g93sdfm2843?ExtIdParam=Id&
ExtStatusParam=Status_t&NewStatus=DOWN&AckStatus=PENDING&
ResolvedStatus=UP HTTP/1.1
Host: connect.signl4.com
Connection: keep-alive
Content-Length: 362
Pragma: no-cache
Cache-Control: no-cache
Content-Type: application/json

{
  "Title": "Critical production failure",
  "Message": "Check line machine C immediately",
  "Severity": "High",
  "Business Details": {
      "Impact": "Major",
      "Scope": "Unlimited"
 },
 "Id": "e3b0c44",
 "Status_t": "IDENTIFIED"
}

Zuweisung einer bestimmten Kategorie

Wenn Sie eine bestimmte Vorfallskategorie aus dem Drittanbietersystem zuweisen möchten, können Sie beim Senden eines neuen Vorfalls den Parameter "X-S4-Service" angeben. Er muss den Namen einer Kategorie im Team enthalten, für die das Signl erstellt werden soll. Er kann mit beliebigen anderen Kontrollparametern kombiniert werden.

{
  "Title": "Critical production failure",
  "Message": "Check line machine C immediately",
  "Severity": "High",
  "Business Details": {
      "Impact": "Major",
      "Scope": "Unlimited"
 },
 "X-S4-ExternalID": "e3b0c44",
 "X-S4-Status": "New",
 "X-S4-Service": "Database"
}

Übermittlung des Geostandorts

Es ist auch möglich, beim Auslösen neuer Signls einen Geostandort anzugeben. Das benachrichtigte Personal kann dann z.B. sehen, wo sich der Vorfall ereignet hat (Karte in den Signldetails) und kann schnell herausfinden, wie man dorthin kommt. Um Standortinformationen zu übermitteln, verwenden Sie den Steuerparameter "X-S4-Location" und übergeben Sie Breiten- und Längengrad, getrennt durch ein Komma, als String-Wert:

{
  "Title": "Critical production failure",
  "Message": "Check line machine C immediately",
  "Severity": "High",
  "Business Details": {
      "Impact": "Major",
      "Scope": "Unlimited"
 },
 "X-S4-ExternalID": "e3b0c44",
 "X-S4-Status": "New",
 "X-S4-Service": "Database",
 "X-S4-Location": "52.4354955,13.0540154"
}

Strickte Filterung von Schlüsselwörtern

SIGNL4-Kategorien können verwendet werden, um das Rauschen herauszufiltern oder eine Klassifizierung auf das eingehende Ereignis anzuwenden. Sie enthalten jeweils eine Einschluss- und eine Ausschlussliste von Schlüsselwörtern, die in dem Ereignis gesucht werden, das Sie z. B. an den Webhook senden. Wenn das Ereignis Wörter enthält, die in der Ausschlussliste (Blockliste) enthalten sind, wird die entsprechende Kategorie dem von Ihnen gesendeten Ereignis nicht zugewiesen. Enthält es dagegen Wörter, die in der Include-Liste (Zulassen-Liste) stehen, wird die Kategorie zugewiesen. Wenn dem Ereignis am Ende keine Kategorie zugewiesen wird, kann es vollständig gefiltert werden, und es würde kein Signal erstellt werden. Infolgedessen würde niemand benachrichtigt werden. Dieses Verhalten kann aktiviert werden, wenn Sie X-S4-Filtering mit einem Wert von true einschließen. Wenn false oder nicht vorhanden ist, wird ein Signl erstellt und der Standardkategorie zugewiesen, wenn es keine bessere Kategorieübereinstimmung gibt.

{
  "Title": "Critical production failure",
  "Message": "Check line machine C immediately",
  "Severity": "High",
  "Business Details": {
      "Impact": "Major",
      "Scope": "Unlimited"
  },
  "X-S4-Filtering": true
}

Verknüpfung mit