AWA-Agent-API

Die AWA-Agent-API (Advanced Work Assignment) bietet Endpunkte für die Verwaltung der Anwesenheit von Service Desk-Mitarbeitern, der Kanalverfügbarkeit und der Arbeitsauslastung.

Diese API erfordert das Plugin Erweiterte Arbeitszuweisung (com.glide.awa) und die Rolle awa_integration_user. Weitere Informationen finden Sie unter Erweiterte Arbeitszuweisung.

AWA Agent – GET /now/awa/agents/{user_id}

Gibt den aktuellen Anwesenheitsstatus des Service Desk-Mitarbeiters und die Kanalverfügbarkeit zurück.

URL-Format

URL mit Versionsnummer: /api/now/{api_version}/awa/agents/{user_id}

Standard-URL: /api/now/awa/agents/{user_id}

Hinweis:

Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

Unterstützte Anforderungsparameter

Tabelle : 1. Pfadparameter

Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge
user_id	Sys_id des Arbeitselements. Das Arbeitselement muss die folgenden Kriterien erfüllen: Das Arbeitselement muss dem angegebenen Service Desk-Mitarbeiter zugewiesen werden. Das Arbeitselement muss sich im Status „Akzeptanz ausstehend“ befinden. Datentyp: Zeichenfolge Tabelle: AWA-Arbeitselement [awa_work_item]

Tabelle : 2. Abfrageparameter

Name	Beschreibung
Keine

Tabelle : 3. Anforderungstextparameter (XML oder JSON)

Header	Beschreibung
Präsenz.Kanäle.Verfügbar	Kennzeichnung, die angibt, ob der Kanal verfügbar ist. Mögliche Werte: wahr: Kanal ist verfügbar. false: Kanal ist nicht verfügbar. Datentyp: Boolesch
präsenz.kanäle.sys_id	sys_id des Kanals Datentyp: Zeichenfolge Tabelle: Servicekanäle [awa_service_channel]
„präsenz.sys_id“	Anwesenheitsstatus-sys_id. Datentyp: Zeichenfolge Tabelle: Anwesenheitsstatus [awa_presence_state]

Header

Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

Tabelle : 4. Anforderungskopfzeilen

Kopfzeile	Beschreibung
Akzeptieren	Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json
Content-Type	Datenformat des Anforderungstexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json

Tabelle : 5. Antwortkopfzeilen

Kopfzeile	Beschreibung
Keine

Statuscodes

Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

Tabelle : 6. Statuscodes

Statuscode	Beschreibung
200	Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
400	Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
401	Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
403	Unzulässig. Mögliche Gründe: Der Benutzer verfügt nicht über die Rolle awa_integration_user. Der Wert der Eigenschaft „glide.awa.enabled“ ist nicht „ true“. Diese Eigenschaft wird in der Tabelle „Systemeigenschaft“ [sys_property] aufgeführt, wenn das Plugin „Erweiterte Arbeitszuweisung“ (com.glide.awa) installiert ist. Weitere Informationen finden Sie unter Mit der erweiterten Arbeitszuweisung installierte Komponenten.
404	Nicht gefunden. Das angeforderte Element wurde nicht gefunden.
500	Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

Parameter des Antworttexts (JSON oder XML)

Tabelle : 7. Parameter des Antworttexts (JSON oder XML)

Parameter	Beschreibung
Fehler	Details, die einen während des Anforderungsprozesses aufgetretenen Fehler beschreiben. Datentyp: Objekt "error": { "detail": "String", "message": "String" }
Fehler.detail	Details des Fehlers, der während des Anforderungsprozesses aufgetreten ist. Datentyp: Zeichenfolge
Fehlernachricht	Meldung für den Fehler, der während des Anforderungsprozesses aufgetreten ist. Jede Fehlermeldung hat eine entsprechende Beschreibung in der Eigenschaft detail. Mögliche Werte: Datensatz nicht gefunden: Die im Anforderungstext angegebenen Informationen sind ungenau oder nicht vorhanden. Anwender nicht authentifiziert: Der Anwender verfügt nicht über die Rolle „awa_integration_user“. Datentyp: Zeichenfolge
Anwesenheit	Informationen über den aktuellen Anwesenheitsstatus und Kanal eines Service Desk-Mitarbeiters. Datentyp: Objekt "presence": { "available": Boolean, "channels": [Array], "name": "String", "sys_id": "String" }
Anwesenheit.verfügbar	Kennzeichnung, die angibt, ob der Service Desk-Mitarbeiter verfügbar ist. Mögliche Werte: wahr: Service Desk-Mitarbeiter ist verfügbar. „falsch“: Service Desk-Mitarbeiter ist nicht verfügbar. Datentyp: Boolesch
präsenz.kanäle	Liste von Objekten, die die verfügbaren Kommunikationskanäle mit dem Service Desk-Mitarbeiter beschreiben. Datentyp: Array von Objekten "channels": [ { "available": Boolean, "name": "String", "sys_id": "String" } ]
Präsenz.Kanäle.Verfügbar	Kennzeichnung, die angibt, ob der Kanal verfügbar ist. Mögliche Werte: wahr: Kanal ist verfügbar. false: Kanal ist nicht verfügbar. Datentyp: Boolesch
presence.channels.name	Kanalname, z. B. Chat oder Telefon. Datentyp: Zeichenfolge
„präsenz.kanäle.beschränken_aktualisieren“	Kennzeichnung, die angibt, ob der Anwender Aktualisierungen einschränken, d. h. den Kanal für die Verfügbarkeit auswählen kann. Mögliche Werte: wahr: Der Anwender kann diesen Kanal für die Verfügbarkeit auswählen. „falsch“: Der Anwender kann diesen Kanal nicht für die Verfügbarkeit auswählen. Datentyp: Boolesch
präsenz.kanäle.service_kanal_typ	Servicekanaltyp, z. B. Chat. Die möglichen Werte variieren je nach installierten Plugins. Datentyp: Zeichenfolge
präsenz.kanäle.sys_id	sys_id des Kanals Datentyp: Zeichenfolge Tabelle: Servicekanäle [awa_service_channel]
presence.name	Name des Anwesenheitsstatus des Service Desk-Mitarbeiters Mögliche Werte: Verfügbar Nicht verfügbar Datentyp: Zeichenfolge
„präsenz.einschränkung_update“	Kennzeichnung, die angibt, ob der Anwender Aktualisierungen einschränken kann. Mögliche Werte: wahr: Der Anwender kann Updates einschränken. „falsch“: Anwender kann Updates nicht einschränken. Datentyp: Boolesch
„präsenz.sys_id“	Anwesenheitsstatus-sys_id. Datentyp: Zeichenfolge Tabelle: Anwesenheitsstatus [awa_presence_state]
status	Status einer nicht erfolgreichen Anforderung. Diese Eigenschaft ist nur in der Antwort enthalten, wenn ein Fehler vorliegt. Gültiger Wert: Fehler Datentyp: Zeichenfolge
sys_id	sys_id des Agenten. Datentyp: Zeichenfolge
workItem	workItem: Informationen zum Arbeitselement, das dem Ereignis zugeordnet ist. Datentyp: Zeichenfolge
workItem.document	workItem.document: Liste der Dokumente, die der Arbeitselementaufgabe zugeordnet sind. Datentyp: Zeichenfolge
workItem.document.sys_id	workItem.document.sys_id: Sys_id des Dokuments, das der Arbeitselementaufgabe zugewiesen ist. Datentyp: Zeichenfolge
workItem.document.table (Arbeitselement.Dokument.Tabelle)	workItem.document.table: Name der Dokumenttabelle, die der Aufgabe zugewiesen ist. Datentyp: Zeichenfolge
workItem.vorherigesArbeitselement	workItem.previousWorkItem: Sys_id des vorherigen Arbeitselements für dieselbe Dokument-ID. Für die Nicht-Transfer-Arbeitselemente ist dieser Wert leer. Datentyp: Zeichenfolge
workItem.serviceChannel	workItem.serviceChannel: Liste der Servicekanäle, die der Arbeitselementaufgabe zugeordnet sind. Datentyp: Zeichenfolge
workItem.serviceChannel.name	workItem.serviceChannel.name: Name des Servicekanals, z. B. Chat oder Telefon. Datentyp: Zeichenfolge
workItem.serviceChannel.sys_id	workItem.serviceChannel.sys_id: Sys_id des Servicekanals. Datentyp: Zeichenfolge
workItem.size	workItem.size: Kapazität des Service Desk-Mitarbeiters, die verwendet wird, wenn dem Service Desk-Mitarbeiter dieses Arbeitselement zugewiesen wird. Datentyp: Zeichenfolge
workItem.sys_id	workItem.sys_id: Sys_id des Arbeitselements, das akzeptiert oder angeboten wurde. Datentyp: Zeichenfolge
workItem.isQueueTransfer	workItem.isQueueTransferred: Kennzeichnung, die angibt, ob das Arbeitselement in der Warteschlange übertragen wird. Auf „wahr“ festlegen, wenn das Arbeitselement in der Warteschlange übertragen wird, andernfalls auf „falsch“. Weitere Informationen zu Warteschlangenübertragungen finden Sie unter Transfer a chat to another queue. Datentyp: Boolesch
workitem.isAutoAccepted	workItem.isAutoAccepted: Kennzeichnung, die angibt, ob das Arbeitselement automatisch vom System akzeptiert wurde. Legen Sie den Wert auf „true“ fest, wenn das Arbeitselement automatisch akzeptiert wurde. Datentyp: Boolesch

Beispiel für eine cURL-Anforderung

curl -X GET \
https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password'\

{
  "result": {
    "presence": {
      "name": "Available",
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3"
        }
      ]
    },
    "sys_id": "46d44a23a9fe19810012d100cca80666"
  }
}

AWA Agent: GET /now/awa/agents/{user_id}/capacities

Gibt die Kanalkapazitäten, die universelle Kapazität und die aktuelle Arbeitsauslastung eines Service Desk-Mitarbeiters zurück, um zu sehen, ob der Service Desk-Mitarbeiter einen Fall bearbeiten kann.

Verwenden Sie die Methode AWA Agent: PUT /now/awa/agents/{user_id}/capacities, um den Kanal und die universellen Kapazitäten eines Service Desk-Mitarbeiters zu ändern.

Siehe auch:

• Kapazität und Nutzung von Servicekanälen
• Erstellen oder konfigurieren Sie einen Servicekanal
• Konfigurieren Sie die maximale universelle Kapazität eines Service Desk-Mitarbeiters

URL-Format

URL mit Versionsnummer: /api/now/{api_version}/awa/agents/{user_id}/capacities

Standard-URL: /api/now/awa/agents/{user_id}/capacities

Hinweis:

Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

Unterstützte Anforderungsparameter

Tabelle : 8. Pfadparameter

Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge
user_id	Sys_id des aufgeführten Agents. Datentyp: Zeichenfolge Tabelle: Benutzer [sys_user]

Tabelle : 9. Abfrageparameter

Name	Beschreibung
Keine

Tabelle : 10. Anforderungstextparameter (XML oder JSON)

Name	Beschreibung
Keine

Kopfzeilen

Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

Tabelle : 11. Anforderungskopfzeilen

Kopfzeile	Beschreibung
Akzeptieren	Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json

Tabelle : 12. Antwortkopfzeilen

Kopfzeile	Beschreibung
Keine

Statuscodes

Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

Tabelle : 13. Statuscodes

Statuscode	Beschreibung
200	Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
400	Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
401	Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
403	Unzulässig. Mögliche Gründe: Der Benutzer verfügt nicht über die Rolle awa_integration_user. Der Wert der Eigenschaft „glide.awa.enabled“ ist nicht „ true“. Diese Eigenschaft wird in der Tabelle „Systemeigenschaft“ [sys_property] aufgeführt, wenn das Plugin „Erweiterte Arbeitszuweisung“ (com.glide.awa) installiert ist. Weitere Informationen finden Sie unter Mit der erweiterten Arbeitszuweisung installierte Komponenten.
404	Nicht gefunden. Das angeforderte Element wurde nicht gefunden.
500	Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

Parameter des Antworttexts (JSON oder XML)

Name	Beschreibung
Kanäle	Liste von Objekten, die die verfügbaren Kommunikationskanäle mit dem Service Desk-Mitarbeiter beschreiben. "channels": [ { "channel_sys_id": "String", "current_workload": Number, "max_capacity": Number } ] Datentyp: Array
„channels.channel_sys_id“	sys_id des Kanals Datentyp: Zeichenfolge Tabelle: Servicekanäle [awa_service_channel]
„channels.current_workload“	Anzahl der Arbeitselemente in einem bestimmten Servicekanal, die dem Service Desk-Mitarbeiter derzeit zugewiesen sind. Datentyp: Zahl
„channels.max_capacity“	Maximale Arbeitsauslastung für einen bestimmten Servicekanal, der der Service Desk-Mitarbeiter gleichzeitig aktiv zugewiesen werden kann. Datentyp: Zeichenfolge
Fehler	Details, die einen während des Anforderungsprozesses aufgetretenen Fehler beschreiben. Datentyp: Objekt "error": { "detail": "String", "message": "String" }
Fehler.detail	Details des Fehlers, der während des Anforderungsprozesses aufgetreten ist. Datentyp: Zeichenfolge
Fehlernachricht	Meldung für den Fehler, der während des Anforderungsprozesses aufgetreten ist. Die Beschreibung wird in der Eigenschaft error.detail angegeben. Datentyp: Zeichenfolge
status	Status einer nicht erfolgreichen Anforderung. Diese Eigenschaft ist nur in der Antwort enthalten, wenn ein Fehler vorliegt. Gültiger Wert: Fehler Datentyp: Zeichenfolge
universell_kapazität	Maximale Kapazität für den Service Desk-Mitarbeiter in allen Servicekanälen. Wenn die aktuelle Arbeitsauslastung eines Service Desk-Mitarbeiters der maximalen universellen Kapazität entspricht, werden dem Service Desk-Mitarbeiter keine zusätzlichen Arbeitselemente zugewiesen. Diese Eigenschaft wird nur zurückgegeben, wenn für diesen Service Desk-Mitarbeiter ein Datensatz für die universelle Kapazität vorhanden ist. Datentyp: Zahl
universell_workload	Anzahl der Arbeitselemente in allen Servicekanälen, die dem angegebenen Service Desk-Mitarbeiter derzeit zugewiesen sind. Diese Eigenschaft wird nur zurückgegeben, wenn für den Service Desk-Mitarbeiter ein Datensatz für die universelle Kapazität vorhanden ist. Datentyp: Zahl

Beispiel für eine cURL-Anforderung

Das folgende Beispiel zeigt, wie die Kapazitäts- und Arbeitsauslastungswerte für einen Benutzer abgerufen werden.

curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Eine erfolgreiche Antwort enthält Kapazitätswerte und Arbeitsauslastung für jeden Kanal.

{
  "result": {
    "universal_workload": 2,
    "channels": [
      {
        "channel_sys_id": "27f675e3739713004a905ee515f6a7c3",
        "current_workload": 2,
        "max_capacity": 4
      }
    ],
    "universal_capacity": 10
  }
}

AWA Agent: GET /now/awa/agents/{user_id}/presence_states

Gibt die Anwesenheitsstatus eines Mitarbeiters zurück und gibt an, ob der Mitarbeiter verfügbar ist oder sich in einem anderen Anwesenheitsstatus befindet.

URL-Format

URL mit Versionsnummer: /api/now/{api_version}/awa/agents/{user_id}/presence_states

Standard-URL: /api/now/awa/agents/{user_id}/presence_states

Hinweis:

Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

Unterstützte Anforderungsparameter

Tabelle : 14. Pfadparameter

Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge
user_id	Sys_id des aufgeführten Agents. Datentyp: Zeichenfolge Tabelle: Benutzer [sys_user]

Tabelle : 15. Abfrageparameter

Name	Beschreibung
Keine

Tabelle : 16. Anforderungstextparameter (XML oder JSON)

Name	Beschreibung
Keine

Kopfzeilen

Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

Tabelle : 17. Anforderungskopfzeilen

Kopfzeile	Beschreibung
Akzeptieren	Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json

Tabelle : 18. Antwortkopfzeilen

Kopfzeile	Beschreibung
Keine

Statuscodes

Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

Tabelle : 19. Statuscodes

Statuscode	Beschreibung
200	Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
400	Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
401	Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
403	Unzulässig. Mögliche Gründe: Der Benutzer verfügt nicht über die Rolle awa_integration_user. Der Wert der Eigenschaft „glide.awa.enabled“ ist nicht „ true“. Diese Eigenschaft wird in der Tabelle „Systemeigenschaft“ [sys_property] aufgeführt, wenn das Plugin „Erweiterte Arbeitszuweisung“ (com.glide.awa) installiert ist. Weitere Informationen finden Sie unter Mit der erweiterten Arbeitszuweisung installierte Komponenten.
404	Nicht gefunden. Das angeforderte Element wurde nicht gefunden.
500	Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

Parameter des Antworttexts (JSON oder XML)

Name	Beschreibung
Fehler	Details, die einen während des Anforderungsprozesses aufgetretenen Fehler beschreiben. Datentyp: Objekt "error": { "detail": "String", "message": "String" }
Fehler.detail	Details des Fehlers, der während des Anforderungsprozesses aufgetreten ist. Datentyp: Zeichenfolge
Fehlernachricht	Meldung für den Fehler, der während des Anforderungsprozesses aufgetreten ist. Die Beschreibung wird in der Eigenschaft error.detail angegeben. Datentyp: Zeichenfolge
<presence state>	Liste der Anwesenheitsstatusdefinitionen des Service Desk-Mitarbeiters als Objekte. Jedes Objekt beschreibt den Status und enthält die Kanäle des Service Desk-Mitarbeiters. Datentyp: Array { "available": Boolean, "channels": [Array], "disable_inactivity_check": Boolean, "name": "String", "show_channels": Boolean, "sys_id": "String" }
<presence state>.verfügbar	Kennzeichnung, die angibt, ob der Service Desk-Mitarbeiter verfügbar ist. Mögliche Werte: wahr: Service Desk-Mitarbeiter ist verfügbar. „falsch“: Service Desk-Mitarbeiter ist nicht verfügbar. Datentyp: Boolesch
<presence state>.Kanäle	Liste von Objekten, die die verfügbaren Kommunikationskanäle mit dem Service Desk-Mitarbeiter beschreiben. Datentyp: Array "channels": [ { "available": Boolean, "name": "String", "restrict_update": Boolean, "service_channel_type": "String", "sys_id": "String" } ]
<presence state>.Kanäle.verfügbar	Kennzeichnung, die angibt, ob der Kanal verfügbar ist. Mögliche Werte: wahr: Kanal ist verfügbar. false: Kanal ist nicht verfügbar. Datentyp: Boolesch
<presence state>.channels.name	Kanalname, z. B. Chat oder Telefon. Datentyp: Zeichenfolge
<presence state>.channels.sys_id	sys_id des Kanals Datentyp: Zeichenfolge Tabelle: Servicekanäle [awa_service_channel]
<presence state>.disable_inactivity_check	Kennzeichnung, die angibt, ob die Inaktivität dieses Anwesenheitsstatus überprüft werden soll. Gültige Werte: wahr: Die Inaktivitätsprüfung des Anwesenheitsstatus ist deaktiviert. „falsch“: Die Inaktivitätsprüfung des Anwesenheitsstatus ist aktiviert. Datentyp: Boolesch Standardwert: false Informationen zum Ändern dieser Einstellung finden Sie unter Anwesenheitsstatus von Service Desk-Mitarbeitern konfigurieren.
<presence state>.name	Name des Anwesenheitsstatus des Service Desk-Mitarbeiters Die standardmäßig installierten Anwesenheitsstatus sind Verfügbar, Abwesendund Offline. Datentyp: Zeichenfolge
<presence state>.auftrag	Reihenfolge, in der dieser Status im Posteingang des Service Desk-Mitarbeiters angezeigt wird. Datentyp: Zahl
<presence state>.show_channels	Kennzeichnung, die angibt, ob der Service Desk-Mitarbeiter berechtigt ist, den Anwesenheitsstatus zu ändern, z. B. von verfügbar in abwesend. Gültige Werte: „wahr“: Der Anwender hat die Berechtigung zum Ändern der Anwesenheit. „falsch“: Der Anwender kann die Anwesenheit nicht ändern. Datentyp: Boolesch
<presence state>.sys_id	Anwesenheitsstatus-sys_id. Datentyp: Zeichenfolge Tabelle: Anwesenheitsstatus [awa_presence_state]
status	Status einer nicht erfolgreichen Anforderung. Diese Eigenschaft ist nur in der Antwort enthalten, wenn ein Fehler vorliegt. Gültiger Wert: Fehler Datentyp: Zeichenfolge

Beispiel für eine cURL-Anforderung

Das folgende Beispiel zeigt, wie die Anwesenheitsstatus für einen bestimmten Service Desk-Mitarbeiter abgerufen werden.

curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/presence_states" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

Der Antworttext listet die möglichen Anwesenheitsstatus des Service Desk-Mitarbeiters auf und gibt an, dass der Service Desk-Mitarbeiter verfügbar ist.

{
  "result": [
    {
      "name": "Available",
      "order": 0,
      "show_channels": false,
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3",
          "restrict_update": false,
          "service_channel_type": "chat"
        }
      ],
      "disable_inactivity_check": false
    },
    {
      "name": "Away",
      "order": 1000,
      "show_channels": false,
      "sys_id": "41f9b8dfb31313005baa6e5f26a8dcac",
      "available": false,
      "channels": [],
      "disable_inactivity_check": false
    },
    {
      "name": "Offline",
      "order": 2000,
      "show_channels": false,
      "sys_id": "9cd83267575313005baaaa65ef94f98b",
      "available": false,
      "channels": [],
      "disable_inactivity_check": false
    }
  ]
}

AWA Agent – PUT /now/awa/agents/{user_id}

Legt den Status der Anwesenheit eines angegebenen Service Desk-Mitarbeiters und, falls angegeben, die Kanalverfügbarkeit des Service Desk-Mitarbeiters für diesen Status fest.

URL-Format

URL mit Versionsnummer: /api/now/{api_version}/awa/agents/{user_id}

Standard-URL: /api/now/awa/agents/{user_id}

Hinweis:

Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

Unterstützte Anforderungsparameter

Tabelle : 20. Pfadparameter

Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge
user_id	Sys_id des Agent. Datentyp: Zeichenfolge Tabelle: Benutzer [sys_user]

Tabelle : 21. Abfrageparameter

Name	Beschreibung
Keine

Tabelle : 22. Anforderungstextparameter (XML oder JSON)

Name	Beschreibung
präsenz.kanäle	Liste von Objekten, die definieren, welche Kanäle für den Service Desk-Mitarbeiter verfügbar sind. Datentyp: Array von Objekten "channels": [ { "available": Boolean, "sys_id": "String" } ]
Präsenz.Kanäle.Verfügbar	Kennzeichnung, die angibt, ob der Kanal verfügbar ist. Mögliche Werte: wahr: Kanal ist verfügbar. false: Kanal ist nicht verfügbar. Hinweis: Diese Einstellung muss angegeben werden, um Kanäle in den Antworttext aufzunehmen. Datentyp: Boolesch Standardwert: false
präsenz.kanäle.sys_id	sys_id des Kanals Datentyp: Zeichenfolge Tabelle: Servicekanäle [awa_service_channel]
„präsenz.sys_id“	Anwesenheitsstatus-sys_id. Datentyp: Zeichenfolge Tabelle: Anwesenheitsstatus [awa_presence_state]

Header

Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

Tabelle : 23. Anforderungskopfzeilen

Kopfzeile	Beschreibung
Akzeptieren	Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json
Content-Type	Datenformat des Anforderungstexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json

Tabelle : 24. Antwortkopfzeilen

Kopfzeile	Beschreibung
Keine

Statuscodes

Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

Tabelle : 25. Statuscodes

Statuscode	Beschreibung
200	Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
400	Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
401	Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
403	Unzulässig. Mögliche Gründe: Der Benutzer verfügt nicht über die Rolle awa_integration_user. Der Wert der Eigenschaft „glide.awa.enabled“ ist nicht „ true“. Diese Eigenschaft wird in der Tabelle „Systemeigenschaft“ [sys_property] aufgeführt, wenn das Plugin „Erweiterte Arbeitszuweisung“ (com.glide.awa) installiert ist. Weitere Informationen finden Sie unter Mit der erweiterten Arbeitszuweisung installierte Komponenten.
404	Nicht gefunden. Das angeforderte Element wurde nicht gefunden.
500	Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

Tabelle : 26. Parameter des Antworttexts (JSON oder XML)

Parameter	Beschreibung
Fehler	Details, die einen während des Anforderungsprozesses aufgetretenen Fehler beschreiben. Datentyp: Objekt "error": { "detail": "String", "message": "String" }
Fehler.detail	Details des Fehlers, der während des Anforderungsprozesses aufgetreten ist. Datentyp: Zeichenfolge
Fehlernachricht	Meldung für den Fehler, der während des Anforderungsprozesses aufgetreten ist. Jede Fehlermeldung hat eine entsprechende Beschreibung in der Eigenschaft detail. Mögliche Werte: Datensatz nicht gefunden: Die im Anforderungstext angegebenen Informationen sind ungenau oder nicht vorhanden. Anwender nicht authentifiziert: Der Anwender verfügt nicht über die Rolle „awa_integration_user“. Datentyp: Zeichenfolge
Anwesenheit	Informationen über den aktuellen Anwesenheitsstatus und Kanal eines Service Desk-Mitarbeiters. Datentyp: Objekt "presence": { "available": Boolean, "channels": [Array], "name": "String", "sys_id": "String" }
Anwesenheit.verfügbar	Kennzeichnung, die angibt, ob der Service Desk-Mitarbeiter verfügbar ist. Mögliche Werte: wahr: Service Desk-Mitarbeiter ist verfügbar. „falsch“: Service Desk-Mitarbeiter ist nicht verfügbar. Datentyp: Boolesch
präsenz.kanäle	Liste von Objekten, die die verfügbaren Kommunikationskanäle mit dem Service Desk-Mitarbeiter beschreiben. Datentyp: Array von Objekten "channels": [ { "available": Boolean, "name": "String", "sys_id": "String" } ]
Präsenz.Kanäle.Verfügbar	Kennzeichnung, die angibt, ob der Kanal verfügbar ist. Mögliche Werte: wahr: Kanal ist verfügbar. false: Kanal ist nicht verfügbar. Datentyp: Boolesch
presence.channels.name	Kanalname, z. B. Chat oder Telefon. Datentyp: Zeichenfolge
„präsenz.kanäle.beschränken_aktualisieren“	Kennzeichnung, die angibt, ob der Anwender Aktualisierungen einschränken, d. h. den Kanal für die Verfügbarkeit auswählen kann. Mögliche Werte: wahr: Der Anwender kann diesen Kanal für die Verfügbarkeit auswählen. „falsch“: Der Anwender kann diesen Kanal nicht für die Verfügbarkeit auswählen. Datentyp: Boolesch
präsenz.kanäle.service_kanal_typ	Servicekanaltyp, z. B. Chat. Die möglichen Werte variieren je nach installierten Plugins. Datentyp: Zeichenfolge
präsenz.kanäle.sys_id	sys_id des Kanals Datentyp: Zeichenfolge Tabelle: Servicekanäle [awa_service_channel]
presence.name	Name des Anwesenheitsstatus des Service Desk-Mitarbeiters Mögliche Werte: Verfügbar Nicht verfügbar Datentyp: Zeichenfolge
„präsenz.einschränkung_update“	Kennzeichnung, die angibt, ob der Anwender Aktualisierungen einschränken kann. Mögliche Werte: wahr: Der Anwender kann Updates einschränken. „falsch“: Anwender kann Updates nicht einschränken. Datentyp: Boolesch
„präsenz.sys_id“	Anwesenheitsstatus-sys_id. Datentyp: Zeichenfolge Tabelle: Anwesenheitsstatus [awa_presence_state]
status	Status einer nicht erfolgreichen Anforderung. Diese Eigenschaft ist nur in der Antwort enthalten, wenn ein Fehler vorliegt. Gültiger Wert: Fehler Datentyp: Zeichenfolge
sys_id	sys_id des Agenten. Datentyp: Zeichenfolge
workItem	workItem: Informationen zum Arbeitselement, das dem Ereignis zugeordnet ist. Datentyp: Zeichenfolge
workItem.document	workItem.document: Liste der Dokumente, die der Arbeitselementaufgabe zugeordnet sind. Datentyp: Zeichenfolge
workItem.document.sys_id	workItem.document.sys_id: Sys_id des Dokuments, das der Arbeitselementaufgabe zugewiesen ist. Datentyp: Zeichenfolge
workItem.document.table (Arbeitselement.Dokument.Tabelle)	workItem.document.table: Name der Dokumenttabelle, die der Aufgabe zugewiesen ist. Datentyp: Zeichenfolge
workItem.vorherigesArbeitselement	workItem.previousWorkItem: Sys_id des vorherigen Arbeitselements für dieselbe Dokument-ID. Für die Nicht-Transfer-Arbeitselemente ist dieser Wert leer. Datentyp: Zeichenfolge
workItem.serviceChannel	workItem.serviceChannel: Liste der Servicekanäle, die der Arbeitselementaufgabe zugeordnet sind. Datentyp: Zeichenfolge
workItem.serviceChannel.name	workItem.serviceChannel.name: Name des Servicekanals, z. B. Chat oder Telefon. Datentyp: Zeichenfolge
workItem.serviceChannel.sys_id	workItem.serviceChannel.sys_id: Sys_id des Servicekanals. Datentyp: Zeichenfolge
workItem.size	workItem.size: Kapazität des Service Desk-Mitarbeiters, die verwendet wird, wenn dem Service Desk-Mitarbeiter dieses Arbeitselement zugewiesen wird. Datentyp: Zeichenfolge
workItem.sys_id	workItem.sys_id: Sys_id des Arbeitselements, das akzeptiert oder angeboten wurde. Datentyp: Zeichenfolge
workItem.isQueueTransfer	workItem.isQueueTransferred: Kennzeichnung, die angibt, ob das Arbeitselement in der Warteschlange übertragen wird. Auf „wahr“ festlegen, wenn das Arbeitselement in der Warteschlange übertragen wird, andernfalls auf „falsch“. Weitere Informationen zu Warteschlangenübertragungen finden Sie unter Transfer a chat to another queue. Datentyp: Boolesch
workitem.isAutoAccepted	workItem.isAutoAccepted: Kennzeichnung, die angibt, ob das Arbeitselement automatisch vom System akzeptiert wurde. Legen Sie den Wert auf „true“ fest, wenn das Arbeitselement automatisch akzeptiert wurde. Datentyp: Boolesch

curl -X PUT \
 https://instance.servicenow.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666 \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password'\
-d '{"presence": {\
  "sys_id": "0b10223c57a313005baaaa65ef94f970",\
  "channels": [{ \
  "sys_id": "0bbdedbb3b892300a2bac9bb34efc445",\
  "available": true
}] 
}}

{
  "result": {
    "presence": {
      "name": "Available",
      "sys_id": "0b10223c57a313005baaaa65ef94f970",
      "available": true,
      "channels": [
        {
          "name": "Chat",
          "available": true,
          "sys_id": "27f675e3739713004a905ee515f6a7c3"
        }
      ]
    },
    "sys_id": "46d44a23a9fe19810012d100cca80666"
  }
}

AWA Agent: PUT /now/awa/agents/{user_id}/capacities

Ermöglicht die Aktualisierung der maximalen Kapazität (Arbeitsauslastung) eines Service Desk-Mitarbeiters für Kanalkapazitäten und universelle Kapazität.

Mit der Methode AWA Agent: GET /now/awa/agents/{user_id}/capacities können Sie den aktuellen Kanal und die universellen Kapazitäten eines Service Desk-Mitarbeiters abrufen.

Siehe auch:

• Kapazität und Nutzung von Servicekanälen
• Erstellen oder konfigurieren Sie einen Servicekanal
• Konfigurieren Sie die maximale universelle Kapazität eines Service Desk-Mitarbeiters

URL-Format

URL mit Versionsnummer: /api/now/{api_version}/awa/agents/{user_id}/capacities

Standard-URL: /api/now/awa/agents/{user_id}/capacities

Hinweis:

Verfügbare Versionen werden im REST-API-Explorerangegeben. Für geskriptete REST APIs finden Sie zusätzliche Versionsinformationen im Formular „Geskripteter REST-Service“.

Unterstützte Anforderungsparameter

Tabelle : 27. Pfadparameter

Name	Beschreibung
api_version	Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden. Datentyp: Zeichenfolge
user_id	Sys_id des aufgeführten Agents. Datentyp: Zeichenfolge Tabelle: Benutzer [sys_user]

Tabelle : 28. Abfrageparameter

Name	Beschreibung
Keine

Tabelle : 29. Anforderungstextparameter (XML oder JSON)

Name	Beschreibung
Kanäle	Obligatorisch, wenn der Höchstwert eines oder mehrerer Kanäle für den angegebenen Agent aktualisiert wird. JSON-Objekt, das mindestens ein Schlüssel-Wert-Paar enthält, das den Kanal seiner maximalen Kapazität für jeden dem Agent zugewiesenen Kanal zuordnet. Datentyp: Objekt Das Paar hat das folgende Format: Schlüssel (Kanal-sys_id) – sys_id des Kanals Datentyp: Zeichenfolge Wert (maximale Kapazität) – Maximale Arbeitsauslastung für einen bestimmten Servicekanal, der der Service Desk-Mitarbeiter gleichzeitig aktiv zugewiesen werden kann. Datentyp: Zahl channels: {"<channel_sys_id>": <max_capacity>}
universell_kapazität	Obligatorisch, wenn die universelle Kapazität aktualisiert wird. Maximale Kapazität für den Service Desk-Mitarbeiter in allen Servicekanälen. Wenn die aktuelle Arbeitsauslastung eines Service Desk-Mitarbeiters der maximalen universellen Kapazität entspricht, werden dem Service Desk-Mitarbeiter keine zusätzlichen Arbeitselemente zugewiesen. Datentyp: Zahl

Header

Die folgenden Anforderungs- und Antwortkopfzeilen gelten nur für diese HTTP-Aktion oder für diese Aktion auf eine bestimmte Weise. Eine Liste der allgemeinen Header, die in der REST API verwendet werden, finden Sie unter Unterstützte REST API-Header.

Tabelle : 30. Anforderungskopfzeilen

Kopfzeile	Beschreibung
Akzeptieren	Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json

Tabelle : 31. Antwortkopfzeilen

Kopfzeile	Beschreibung
Keine

Statuscodes

Die folgenden Statuscodes gelten für diese HTTP-Aktion. Eine Liste der möglichen Statuscodes, die in der REST API verwendet werden, finden Sie unter HTTP-Antwortcodes der REST-API.

Tabelle : 32. Statuscodes

Statuscode	Beschreibung
200	Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
400	Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
404	Nicht gefunden. Das angeforderte Element wurde nicht gefunden.

Parameter des Antworttexts (JSON oder XML)

Name	Beschreibung
Kanäle	Liste von Objekten, die die verfügbaren Kommunikationskanäle mit dem Service Desk-Mitarbeiter beschreiben. "channels": [ { "channel_sys_id": "String", "max_capacity": Number } ] Datentyp: Array
„channels.channel_sys_id“	sys_id des Kanals Datentyp: Zeichenfolge Tabelle: Servicekanäle [awa_service_channel]
„channels.max_capacity“	Maximale Arbeitsauslastung für einen bestimmten Servicekanal, der der Service Desk-Mitarbeiter gleichzeitig aktiv zugewiesen werden kann. Datentyp: Zeichenfolge
Fehler	Details, die einen während des Anforderungsprozesses aufgetretenen Fehler beschreiben. Datentyp: Objekt "error": { "detail": "String", "message": "String" }
Fehler.detail	Details des Fehlers, der während des Anforderungsprozesses aufgetreten ist. Datentyp: Zeichenfolge
Fehlernachricht	Meldung für den Fehler, der während des Anforderungsprozesses aufgetreten ist. Die Beschreibung wird in der Eigenschaft error.detail angegeben. Datentyp: Zeichenfolge
status	Status einer nicht erfolgreichen Anforderung. Diese Eigenschaft ist nur in der Antwort enthalten, wenn ein Fehler vorliegt. Gültiger Wert: Fehler Datentyp: Zeichenfolge
universell_kapazität	Maximale Kapazität für den Service Desk-Mitarbeiter in allen Servicekanälen. Wenn die aktuelle Arbeitsauslastung eines Service Desk-Mitarbeiters der maximalen universellen Kapazität entspricht, werden dem Service Desk-Mitarbeiter keine zusätzlichen Arbeitselemente zugewiesen. Diese Eigenschaft wird nur zurückgegeben, wenn für diesen Service Desk-Mitarbeiter ein Datensatz für die universelle Kapazität vorhanden ist. Datentyp: Zahl

Beispiel für eine cURL-Anforderung

Das folgende Beispiel zeigt, wie die universelle Kapazität eines Service Desk-Mitarbeiters und die maximale Kapazität für einen angegebenen Kanal geändert werden.

curl "https://instance.service-now.com/api/now/awa/agents/46d44a23a9fe19810012d100cca80666/capacities" \
--request PUT \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
 \"channels\": { \"27f675e3739713004a905ee515f6a7c3\": 6 },
 \"universal_capacity\" : 12
}" \
--user 'username':'password'

Eine erfolgreiche Antwort enthält die aktualisierten Kapazitätswerte.

{
  "result": {
    "channels": [
      {
        "channel_sys_id": "27f675e3739713004a905ee515f6a7c3",
        "max_capacity": 6
      }
    ],
    "universal_capacity": 12
  }
}