AWA-Agent-API

  • Freigeben Version: Washingtondc
  • Aktualisiert 1. Februar 2024
  • 17 Minuten Lesedauer

    • Die AWA-Agent-API (Advanced Work Assignment) bietet Endpunkte für die Verwaltung der Agentenpräsenz, 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 Advanced Work Assignment.

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

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

    URL-Format

    Versionierte URL: /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 Arbeitselements, das in der Tabelle „AWA-Arbeitselement“ [awa_work_item] aufgeführt ist.
    Das Arbeitselement muss die folgenden Kriterien erfüllen:
    • Arbeitselement muss dem angegebenen Service Desk-Mitarbeiter zugewiesen werden.
    • Das Arbeitselement muss sich im Status „ Akzeptanz steht aus“ 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:
    • true: 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 „Advanced Work Assignment“ (com.glide.awa) installiert ist. Weitere Informationen finden Sie unter Mit Advanced Work Assignment 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.

    Antworttextparameter (JSON oder XML)

    Tabelle : 7. Antworttextparameter (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 während des Anforderungsprozesses aufgetretenen Fehlers.

    Datentyp: Zeichenfolge
    Fehler.Nachricht Meldung für den während des Anforderungsprozesses aufgetretenen Fehler. Jede Fehlermeldung hat eine entsprechende Beschreibung in der Eigenschaft detail.
    Mögliche Werte:
    • Datensatz nicht gefunden : Die im Anforderungstext angegebenen Informationen sind falsch oder nicht vorhanden.
    • Anwender nicht authentifiziert : 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 Agent verfügbar ist.
    Mögliche Werte:
    • true: Agent ist verfügbar.
    • false: Agent ist nicht verfügbar.

    Datentyp: Boolesch
    presence.channels Liste der Objekte, 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:
    • true: 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.restrict_update“. Kennzeichnung, die angibt, ob der Benutzer Updates einschränken kann, d. h. den Kanal für die Verfügbarkeit auswählen.
    Mögliche Werte:
    • true: Der Benutzer kann diesen Kanal für die Verfügbarkeit auswählen.
    • false: Der Benutzer 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 Benutzer Updates einschränken kann.
    Mögliche Werte:
    • true: Benutzer kann Updates einschränken.
    • false: Benutzer 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 wird nur in die Antwort aufgenommen, wenn ein Fehler vorliegt.

    Gültiger Wert: Fehler

    Datentyp: Zeichenfolge
    sys_id sys_id des Agenten.

    Datentyp: Zeichenfolge

    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 festzustellen, ob der Service Desk-Mitarbeiter einen Fall bearbeiten kann.

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

    Siehe auch:

    URL-Format

    Versionierte URL: /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 Service Desk-Mitarbeiters, der in der Benutzertabelle [sys_user] aufgeführt ist.

    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 „Advanced Work Assignment“ (com.glide.awa) installiert ist. Weitere Informationen finden Sie unter Mit Advanced Work Assignment 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.

    Antworttextparameter (JSON oder XML)

    Name Beschreibung
    Kanäle Liste der Objekte, 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
    kanäle.channel_sys_id sys_id des Kanals. Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

    Datentyp: Zeichenfolge
    Kanäle.Aktuelle_Arbeitslast Anzahl der Arbeitselemente in einem bestimmten Servicekanal, die dem Service Desk-Mitarbeiter derzeit zugewiesen sind.

    Datentyp: Zahl
    Kanäle.max_capacity Die 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 während des Anforderungsprozesses aufgetretenen Fehlers.

    Datentyp: Zeichenfolge
    Fehler.Nachricht Meldung für den während des Anforderungsprozesses aufgetretenen Fehler. Die Beschreibung wird in der Eigenschaft error.detail bereitgestellt.

    Datentyp: Zeichenfolge
    status Status einer nicht erfolgreichen Anforderung. Diese Eigenschaft wird nur in die Antwort aufgenommen, wenn ein Fehler vorliegt.

    Gültiger Wert: Fehler

    Datentyp: Zeichenfolge
    universal_capacity Maximale Kapazität für den Service Desk-Mitarbeiter über alle Servicekanäle hinweg. 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 Agent ein Datensatz für die universelle Kapazität vorhanden ist.

    Datentyp: Zahl
    universal_workload Anzahl der Arbeitselemente in allen Servicekanälen, die derzeit dem angegebenen Service Desk-Mitarbeiter 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 Service Desk-Mitarbeiters zurück und gibt an, ob der Service Desk-Mitarbeiter verfügbar ist oder sich in einem anderen Anwesenheitsstatus befindet.

    URL-Format

    Versionierte URL: /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 Service Desk-Mitarbeiters, der in der Benutzertabelle [sys_user] aufgeführt ist.

    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 „Advanced Work Assignment“ (com.glide.awa) installiert ist. Weitere Informationen finden Sie unter Mit Advanced Work Assignment 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.

    Antworttextparameter (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 während des Anforderungsprozesses aufgetretenen Fehlers.

    Datentyp: Zeichenfolge
    Fehler.Nachricht Meldung für den während des Anforderungsprozesses aufgetretenen Fehler. Die Beschreibung wird in der Eigenschaft error.detail bereitgestellt.

    Datentyp: Zeichenfolge
    <presence state> Liste der Definitionen des Anwesenheitsstatus 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 Agent verfügbar ist.
    Mögliche Werte:
    • true: Agent ist verfügbar.
    • false: Agent ist nicht verfügbar.

    Datentyp: Boolesch
    <presence state>.Kanäle Liste der Objekte, 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:
    • true: Kanal ist verfügbar.
    • false: Kanal ist nicht verfügbar.

    Datentyp: Boolesch
    <presence state>.Kanäle.Name Kanalname, z. B. Chat oder Telefon.

    Datentyp: Zeichenfolge
    <presence state>.Kanäle.sys_id sys_id des Kanals. Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

    Datentyp: Zeichenfolge
    <presence state>.disable_inaktivität_check Kennzeichnung, die angibt, ob die Inaktivität dieses Anwesenheitsstatus überprüft werden soll.
    Gültige Werte:
    • true: Die Inaktivitätsprüfung des Anwesenheitsstatus ist deaktiviert.
    • false: Die Inaktivitätsprüfung des Anwesenheitsstatus ist aktiviert.

    Datentyp: Boolesch

    Standardwert: false

    Informationen zum Ändern dieser Einstellung finden Sie unter Agent-Anwesenheitsstatus 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>.Reihenfolge 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:
    • true: Der Benutzer hat die Berechtigung, die Anwesenheit zu ändern.
    • false: Der Benutzer darf 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 wird nur in die Antwort aufgenommen, 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 angegebenen 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 fest und legt, falls vorhanden, die Kanalverfügbarkeit des Service Desk-Mitarbeiters für diesen Status fest.

    URL-Format

    Versionierte URL: /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 Benutzertabelle [sys_user].

    Datentyp: Zeichenfolge
    Tabelle : 21. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 22. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    presence.channels Liste der Objekte, 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:
    • true: 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 „Advanced Work Assignment“ (com.glide.awa) installiert ist. Weitere Informationen finden Sie unter Mit Advanced Work Assignment 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. Antworttextparameter (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 während des Anforderungsprozesses aufgetretenen Fehlers.

    Datentyp: Zeichenfolge
    Fehler.Nachricht Meldung für den während des Anforderungsprozesses aufgetretenen Fehler. Jede Fehlermeldung hat eine entsprechende Beschreibung in der Eigenschaft detail.
    Mögliche Werte:
    • Datensatz nicht gefunden : Die im Anforderungstext angegebenen Informationen sind falsch oder nicht vorhanden.
    • Anwender nicht authentifiziert : 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 Agent verfügbar ist.
    Mögliche Werte:
    • true: Agent ist verfügbar.
    • false: Agent ist nicht verfügbar.

    Datentyp: Boolesch
    presence.channels Liste der Objekte, 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:
    • true: 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.restrict_update“. Kennzeichnung, die angibt, ob der Benutzer Updates einschränken kann, d. h. den Kanal für die Verfügbarkeit auswählen.
    Mögliche Werte:
    • true: Der Benutzer kann diesen Kanal für die Verfügbarkeit auswählen.
    • false: Der Benutzer 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 Benutzer Updates einschränken kann.
    Mögliche Werte:
    • true: Benutzer kann Updates einschränken.
    • false: Benutzer 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 wird nur in die Antwort aufgenommen, wenn ein Fehler vorliegt.

    Gültiger Wert: Fehler

    Datentyp: Zeichenfolge
    sys_id sys_id des Agenten.

    Datentyp: Zeichenfolge

    		 
    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

    Verwenden Sie die Methode AWA Agent – GET /now/awa/agents/{user_id}/capacities, um den aktuellen Kanal und die universellen Kapazitäten eines Service Desk-Mitarbeiters abzurufen.

    Siehe auch:

    URL-Format

    Versionierte URL: /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 Service Desk-Mitarbeiters, der in der Benutzertabelle [sys_user] aufgeführt ist.

    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 Service Desk-Mitarbeiter aktualisiert wird. JSON-Objekt, das ein oder mehrere Schlüssel-Wert-Paare enthält, die den Kanal seiner maximalen Kapazität für jeden dem Agent zugewiesenen Kanal zuordnen.

    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 Arbeitsauslastung für einen bestimmten Servicekanal, der der Service Desk-Mitarbeiter gleichzeitig aktiv zugewiesen werden kann.

      Datentyp: Zahl

    channels: {"<channel_sys_id>": <max_capacity>}
    universal_capacity Obligatorisch, wenn die universelle Kapazität aktualisiert wird. Maximale Kapazität für den Service Desk-Mitarbeiter über alle Servicekanäle hinweg. 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.

    Antworttextparameter (JSON oder XML)

    Name Beschreibung
    Kanäle Liste der Objekte, die die verfügbaren Kommunikationskanäle mit dem Service Desk-Mitarbeiter beschreiben. 
    "channels": [
  {
    "channel_sys_id": "String",
    "max_capacity": Number
  }
]

    Datentyp: Array
    kanäle.channel_sys_id sys_id des Kanals. Befindet sich in der Tabelle „Servicekanäle“ [awa_service_channel].

    Datentyp: Zeichenfolge
    Kanäle.max_capacity Die 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 während des Anforderungsprozesses aufgetretenen Fehlers.

    Datentyp: Zeichenfolge
    Fehler.Nachricht Meldung für den während des Anforderungsprozesses aufgetretenen Fehler. Die Beschreibung wird in der Eigenschaft error.detail bereitgestellt.

    Datentyp: Zeichenfolge
    status Status einer nicht erfolgreichen Anforderung. Diese Eigenschaft wird nur in die Antwort aufgenommen, wenn ein Fehler vorliegt.

    Gültiger Wert: Fehler

    Datentyp: Zeichenfolge
    universal_capacity Maximale Kapazität für den Service Desk-Mitarbeiter über alle Servicekanäle hinweg. 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 Agent 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 des 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
  }
}