Verwendung von Advanced Queries in der ServiceNow API

Die Verwendung erweiterter Abfragen in der ServiceNow REST API ermöglicht eine präzise Steuerung darüber, welche Datensätze von externen Tools abgerufen, gefiltert und verarbeitet werden. Über die sogenannte Encoded-Query-Syntax im Parameter sysparm_query lassen sich komplexe SQL-ähnliche WHERE-Bedingungen abbilden – einschließlich AND/OR-Verknüpfungen, gruppierter Bedingungen, relativer Datumsfilter, Textsuchen und Listenoperationen. Wer Operatoren wie ^, ^OR und ^NQ sowie Parameter für Pagination und Anzeige sicher beherrscht, schafft performante, saubere und skalierbare Integrationen zwischen ServiceNow und Analytics-Plattformen wie Noreja.

ServiceNow „WHERE“-Grundlagen (Encoded Query)

In der REST Table API von ServiceNow übergibst du in sysparm_query einen einzelnen String, der wie eine SQL-WHERE-Klausel funktioniert. Dieser wird Encoded Query genannt.

Feld + Operator + Wert, verbunden durch Carets:

fieldOPvalue^field2OPvalue2...

AND ist ^

OR ist ^OR

OR-Gruppierung / Trennung unabhängiger Klauseln mit ^NQ

Typischerweise nutzt du außerdem hilfreiche Parameter wie:

sysparm_fields=... (Spalten auswählen)

sysparm_limit=... (Zeilenbegrenzung)

sysparm_display_value=true (Anzeige-/Display-Werte zurückgeben)

sysparm_exclude_reference_link=true (sauberere Referenzen)

sysparm_query_no_domain=true (falls Domain-Separation ignoriert werden soll)

Operator-Übersicht

Zweck	Encoded Operator	Beispiel
Gleich	`=`	`state=2`
Ungleich	`!=`	`state!=6`
Größer / Kleiner	`>`, `<`, `>=`, `<=`	`priority<=2`
In Liste	`IN` (Komma-separiert)	`priorityIN1,2,3`
Nicht in Liste	`NOT IN`	`assignment_groupNOT INd625dc6c6fdd...`
Enthält (nicht case-sensitiv)	`LIKE` oder `CONTAINS`	`short_descriptionLIKEemail`
Beginnt mit	`STARTSWITH`	`caller_id.emailSTARTSWITHjohn`
Endet mit	`ENDSWITH`	`u_reference_idENDSWITH-2025`
Leer / Nicht leer	`ISEMPTY`, `ISNOTEMPTY`	`closed_atISEMPTY`
Instanz von (Klasse)	`INSTANCEOF`	`sys_class_nameINSTANCEOFtask`
Zwischen Datumswerten (über zwei Operatoren)	`>=` und `<=`	`sys_updated_on>=2025-08-01^sys_updated_on<=2025-08-23 23:59:59`

Hinweise

LIKE und CONTAINS werden häufig austauschbar für Teilstring-Suchen verwendet.
Die meisten Textvergleiche sind nicht case-sensitiv.
Werte mit Leerzeichen oder Sonderzeichen sollten in der finalen Anfrage URL-kodiert werden.

Logik aufbauen: AND, OR, Gruppierung

AND (^)

active=true^priority<=2

OR (^OR)

priority=1^ORpriority=2

Tipp: Du kannst viele ^OR...-Teile aneinanderreihen.

Gruppierung mit `^NQ`

^NQ startet eine neue Query-Klausel, die per OR mit der gesamten vorherigen Klausel verknüpft wird. Das ist der Trick für
„(A AND B) OR (C AND D)“.

(active=true^priority=1)^NQ(state=2^assignment_group=287ebd7da9fe198100f92cc8d1d2154e)

Gelesen als: (active=true AND priority=1) OR (state=2 AND assignment_group=...).

Text-Operationen & „Wildcards“

Du verwendest bei LIKE kein % oder *; der Operator impliziert bereits eine Teilübereinstimmung.

Enthält: short_descriptionLIKEemail

Beginnt mit: u_ticket_idSTARTSWITHABC-

Endet mit: u_ticket_idENDSWITH-42

Enthält nicht: short_descriptionDOESNOTCONTAINphish

Wenn Sonderzeichen wörtlich gematcht werden müssen (z. B. ^ innerhalb eines Werts), URL-kodiere sie in der Anfrage. In ServiceNow-Listenfiltern sieht man teilweise Escaping mit \; für REST solltest du auf URL-Encoding setzen.

Datumswerte & relative Zeit

Du kannst mit absoluten Zeitstempeln (in der Zeitzone der Instanz) vergleichen oder die relativen Datums-Makros von ServiceNow nutzen.

Absolut

sys_updated_on>=2025-08-01 00:00:00^sys_updated_on<=2025-08-23 23:59:59

Relativ (serverseitige JS-Makros)

sys_updated_on>=javascript:gs.daysAgoStart(7)

Häufige Makros:

gs.daysAgoStart(n), gs.daysAgoEnd(n)

gs.beginningOfLastMonth(), gs.endOfLastMonth()

gs.hoursAgoStart(n) usw.

Praktisch für „letzte 7 Tage“, „heute“, „diesen Monat“ usw., ohne feste Daten zu hinterlegen.

Pagination, Felder und Display-Werte

Limit: sysparm_limit=100 (Standard ist oft 10)

Offset: sysparm_offset=0 (eigene Pagination)

Felder: sysparm_fields=number,short_description,priority,state

Display-Werte: sysparm_display_value=true, um menschenlesbare Strings für Referenzen und Auswahlfelder zu erhalten.

Gruppierte Logik mit `^OR` vs. `^NQ`

Verwendung von ^OR (innerhalb einer Gruppe)

„Priority 1 ODER 2, UND active“

priority=1^ORpriority=2^active=true

Dies wird von links nach rechts ausgewertet, mit impliziten ANDs zwischen den Carets. ^OR hat eine geringere Priorität als die explizite Gruppierung mit ^NQ. In den meisten Praxisfällen verhält sich das wie erwartet.

Verwendung von ^NQ (zwischen Gruppen)

„(active UND priority 1) ODER (state ist On Hold UND in den letzten 7 Tagen aktualisiert)“

active=true^priority=1^NQstate=3^sys_updated_on>=javascript:gs.daysAgoStart(7)