AWA-Agent-API

  • Freigeben Version: Xanadu
  • Aktualisiert 1. August 2024
  • 19 Minuten Lesedauer

    • 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}

    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 in der Tabelle „AWA-Arbeitselement“ [awa_work_item] aufgeführten 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 : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstextparameter (XML oder JSON)
    Header Beschreibung
    presence.channels.available 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.sys_id sys_id des Kanals Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

    Datentyp: Zeichenfolge
    presence.sys_id Anwesenheitsstatus-sys_id. Befindet sich in der Tabelle „Anwesenheitsstatus“ [awa_presence_state].

    Datentyp: Zeichenfolge

    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-Antwortcodesder 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
    presence Informationen über den aktuellen Anwesenheitsstatus und Kanal eines Service Desk-Mitarbeiters.

    Datentyp: Objekt

    "presence": {
  "available": Boolean,
  "channels": [Array],
  "name": "String",
  "sys_id": "String"
}
    presence.available 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.channels Liste von Objekten, die die verfügbaren Kommunikationskanäle mit dem Service Desk-Mitarbeiter beschreiben.

    Datentyp: Array

    "channels": [
 {
  "available": Boolean,
  "name": "String",
  "sys_id": "String"
 }
]
    presence.channels.available 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
    presence.channels.sys_id sys_id des Kanals Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

    Datentyp: Zeichenfolge
    presence.name Name des Anwesenheitsstatus des Service Desk-Mitarbeiters
    Mögliche Werte:
    • Verfügbar
    • Nicht verfügbar

    Datentyp: Zeichenfolge
    presence.restrict_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
    presence.sys_id Anwesenheitsstatus-sys_id. Befindet sich in der Tabelle „Anwesenheitsstatus“ [awa_presence_state].

    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
    sys_id sys_id des Agenten.

    Datentyp: Zeichenfolge
    workItem

    workItem: Informationen zum Arbeitselement, das dem Ereignis zugeordnet ist.
    workItem.document workItem.document: Liste der Dokumente, die der Arbeitselementaufgabe zugeordnet sind.
    workItem.document.sys_id workItem.document.sys_id: Sys_id des Dokuments, das der Arbeitselementaufgabe zugewiesen ist.
    workItem.document.table (Arbeitselement.Dokument.Tabelle) workItem.document.table: Name der Dokumenttabelle, die der Aufgabe zugewiesen ist.
    workItem.vorherigesArbeitselement workItem.previousWorkItem: Sys_id des vorherigen Arbeitselements für dieselbe Dokument-ID. Für die Nicht-Transfer-Arbeitselemente ist dieser Wert leer.
    workItem.serviceChannel workItem.serviceChannel: Liste der Servicekanäle, die der Arbeitselementaufgabe zugeordnet sind.
    workItem.serviceChannel.name workItem.serviceChannel.name: Name des Servicekanals, z. B. Chat oder Telefon.
    workItem.serviceChannel.sys_id workItem.serviceChannel.sys_id: Sys_id des Servicekanals.
    workItem.size workItem.size: Kapazität des Service Desk-Mitarbeiters, die verwendet wird, wenn dem Service Desk-Mitarbeiter dieses Arbeitselement zugewiesen wird.
    workItem.sys_id workItem.sys_id: Sys_id des Arbeitselements, das akzeptiert oder angeboten wurde.
    workItem.isQueueTransfer workItem.isQueueTransferred: Gibt an, 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.

    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:

    URL-Format

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

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

    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 in der Benutzertabelle [sys_user] aufgeführten Agents.

    Datentyp: Zeichenfolge
    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-Antwortcodesder 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 Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

    Datentyp: Zeichenfolge
    „channels.current_workload“ Anzahl der Arbeitselemente in einem bestimmten Servicekanal, die dem Service Desk-Mitarbeiter derzeit zugewiesen sind.

    Datentyp: Zahl
    „channels.max_capacity“ Die maximale Auslastung 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

    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 in der Benutzertabelle [sys_user] aufgeführten Agents.

    Datentyp: Zeichenfolge
    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-Antwortcodesder 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 Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

    Datentyp: Zeichenfolge
    <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. Befindet sich in der Tabelle „Anwesenheitsstatus“ [awa_presence_state].

    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

    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}

    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. Befindet sich in der Tabelle „Benutzer“ [sys_user].

    Datentyp: Zeichenfolge
    Tabelle : 21. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 22. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    presence.channels Liste von Objekten, die definieren, welche Kanäle für den Service Desk-Mitarbeiter verfügbar sind.
    Datentyp: Array
    "channels": [
  { 
    "available": Boolean,
    "sys_id": "String"
  }
]
    presence.channels.available 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
    presence.channels.sys_id sys_id des Kanals Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

    Datentyp: Zeichenfolge
    presence.sys_id Anwesenheitsstatus-sys_id. Befindet sich in der Tabelle „Anwesenheitsstatus“ [awa_presence_state].

    Datentyp: Zeichenfolge

    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-Antwortcodesder 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
    presence Informationen über den aktuellen Anwesenheitsstatus und Kanal eines Service Desk-Mitarbeiters.

    Datentyp: Objekt

    "presence": {
  "available": Boolean,
  "channels": [Array],
  "name": "String",
  "sys_id": "String"
}
    presence.available 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.channels Liste von Objekten, die die verfügbaren Kommunikationskanäle mit dem Service Desk-Mitarbeiter beschreiben.

    Datentyp: Array

    "channels": [
 {
  "available": Boolean,
  "name": "String",
  "sys_id": "String"
 }
]
    presence.channels.available 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
    presence.channels.sys_id sys_id des Kanals Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

    Datentyp: Zeichenfolge
    presence.name Name des Anwesenheitsstatus des Service Desk-Mitarbeiters
    Mögliche Werte:
    • Verfügbar
    • Nicht verfügbar

    Datentyp: Zeichenfolge
    presence.restrict_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
    presence.sys_id Anwesenheitsstatus-sys_id. Befindet sich in der Tabelle „Anwesenheitsstatus“ [awa_presence_state].

    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
    sys_id sys_id des Agenten.

    Datentyp: Zeichenfolge
    workItem

    workItem: Informationen zum Arbeitselement, das dem Ereignis zugeordnet ist.
    workItem.document workItem.document: Liste der Dokumente, die der Arbeitselementaufgabe zugeordnet sind.
    workItem.document.sys_id workItem.document.sys_id: Sys_id des Dokuments, das der Arbeitselementaufgabe zugewiesen ist.
    workItem.document.table (Arbeitselement.Dokument.Tabelle) workItem.document.table: Name der Dokumenttabelle, die der Aufgabe zugewiesen ist.
    workItem.vorherigesArbeitselement workItem.previousWorkItem: Sys_id des vorherigen Arbeitselements für dieselbe Dokument-ID. Für die Nicht-Transfer-Arbeitselemente ist dieser Wert leer.
    workItem.serviceChannel workItem.serviceChannel: Liste der Servicekanäle, die der Arbeitselementaufgabe zugeordnet sind.
    workItem.serviceChannel.name workItem.serviceChannel.name: Name des Servicekanals, z. B. Chat oder Telefon.
    workItem.serviceChannel.sys_id workItem.serviceChannel.sys_id: Sys_id des Servicekanals.
    workItem.size workItem.size: Kapazität des Service Desk-Mitarbeiters, die verwendet wird, wenn dem Service Desk-Mitarbeiter dieses Arbeitselement zugewiesen wird.
    workItem.sys_id workItem.sys_id: Sys_id des Arbeitselements, das akzeptiert oder angeboten wurde.
    workItem.isQueueTransfer workItem.isQueueTransferred: Gibt an, 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. 
    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:

    URL-Format

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

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

    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 in der Benutzertabelle [sys_user] aufgeführten Agents.

    Datentyp: Zeichenfolge
    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 Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

      Datentyp: Zeichenfolge

    • Wert (maximale Kapazität) – Die maximale Auslastung 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-Antwortcodesder 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 Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

    Datentyp: Zeichenfolge
    „channels.max_capacity“ Die maximale Auslastung 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
  }
}