API für AWA-Posteingangsaktionen

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

    • Stellt Endpunkte bereit, um ein Arbeitselement im Namen eines Service Desk-Mitarbeiters zu akzeptieren oder abzulehnen. Diese API ruft auch Ablehnungsgründe für abgelehnte Arbeitselemente ab.

    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-Posteingangsaktionen – GET /awa/inbox/actions/reject_reasons/{channel_id}

    Ruft die Gründe für die Ablehnung des Arbeitselements für einen angegebenen Servicekanal ab.

    URL-Format

    Versionierte URL: /api/now/awa/inbox/actions/reject_reasons/{channel_id}

    Standard-URL: /api/now/{api_version}/awa/inbox/actions/reject_reasons/{channel_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
    channel_id Sys_id eines Servicekanals, der in der Tabelle „Servicekanäle“ [awa_service_channel] aufgeführt ist. Diesbezügliche Informationen finden Sie unter .
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. 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 : 4. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. 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 Datensatz nicht gefunden Die angegebene Kanal-ID ist ungültig.
    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
    display_value Anzeigewert des Felds Grund in der Tabelle „Ablehnungsgründe“ [awa_reject_reason].

    Datentyp: Zeichenfolge
    Bestellen Reihenfolge, in der die Ablehnungsgründe im Posteingang des Service Desk-Mitarbeiters aufgelistet werden.

    Datentyp: Zahl
    Wert Wert des in der Datenbank gespeicherten Felds für den Ablehnungsgrund.

    Datentyp: Zeichenfolge
    Sys_id Sys_id eines Ablehnungsgrunds für diesen Servicekanal. Gründe sind in der Tabelle „Ablehnungsgründe“ [awa_reject_reason] aufgeführt.

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie Ablehnungsgründe für den Chat-Servicekanal abgerufen werden.

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject_reasons/27f675e3739713004a905ee515f6a7c3" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'

    Antworttext, der abgelehnte Aufgaben mit Gründen für die Ablehnung anzeigt.

    {
  "result": [
    {
      "order": 2,
      "value": "Not my expertise",
      "display_value": "Not my expertise",
      "sys_id": "31e3fa29b38023002e7b6e5f26a8dc17"
    },
    {
      "order": 1,
      "value": "Busy",
      "display_value": "Busy",
      "sys_id": "4e93fa29b38023002e7b6e5f26a8dc20"
    }
  ]
}

    AWA-Posteingangsaktionen – POST /awa/inbox/actions/accept

    Akzeptiert ein Arbeitselement im Status „ Akzeptanz steht aus“ im Namen eines Service Desk-Mitarbeiters.

    URL-Format

    Versionierte URL: /api/now/{api_version}/awa/inbox/actions/accept

    Standard-URL: /api/now/awa/inbox/actions/accept

    Unterstützte Anforderungsparameter

    Tabelle : 7. 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
    Tabelle : 8. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 9. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    agent_id Sys_id des Service Desk-Mitarbeiters, der in der Benutzertabelle [sys_user] aufgeführt ist.

    Datentyp: Zeichenfolge
    work_item_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

    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 : 10. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml.

    Standard: application/json
    Tabelle : 11. 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 : 12. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Ungültige Anforderung.
    Mögliche Gründe:
    • Agent-ID fehlt.
    • Arbeitselement-ID fehlt.
    • Arbeitselement ist einem anderen Service Desk-Mitarbeiter zugewiesen.
    • Arbeitselement befindet sich nicht im Akzeptanzstatus „Ausstehend“.
    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.
    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
    documentTable Name der Tabelle mit dem Dokument, das diesem Arbeitselement zugewiesen ist.

    Datentyp: Zeichenfolge
    documentSysId Sys_id des Dokumentdatensatzes, der der Aufgabe zugewiesen ist. Befindet sich in der Tabelle, die im Feld documentTable angegeben ist.

    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.
    Mögliche Werte:
    • Fehlende Agent-ID : agent_id wurde im Anforderungstext nicht angegeben.
    • Fehlende Arbeitselement-ID : work_item_id wurde im Anforderungstext nicht angegeben.
    • Arbeitselement ist einem anderen Service Desk-Mitarbeiter zugewiesen: Das angegebene Arbeitselement ist nicht dem angegebenen Service Desk-Mitarbeiter zugewiesen.
    • Falsche Arbeitselement-ID : Das im Anforderungstext angegebene Arbeitselement ist falsch oder nicht vorhanden.
    • Arbeitselement befindet sich nicht im Akzeptanzstatus „Ausstehend“ –Das im Anforderungstext angegebene Arbeitselement befindet sich in einem anderen Status als „Akzeptanz steht aus“.

    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

    cURL-Anforderung

    Das folgende Beispiel zeigt, wie Sie den Status des Arbeitselements eines ausgewählten Service Desk-Mitarbeiters von Akzeptanz steht aus in Akzeptiertändern.

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/accept" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
 \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
 \"work_item_id\":\"fd69abfc878b01101ae365b83cbb35fe\"
}" \
--user 'username':'password'

    Der Antworttext listet die sys_id und die Tabelle des Dokuments auf, das sich auf das Arbeitselement bezieht.

    {
  "result": {
    "documentSysId": "57af7aec73d423002728660c4cf6a71c",
    "documentTable": "incident"
  }
}

    AWA-Posteingangsaktionen – POST /awa/inbox/actions/reject

    Lehnt ein Arbeitselement im Status „ Akzeptanz steht aus“ im Namen eines Service Desk-Mitarbeiters ab. Bei Erfolg ist das Feld „Zugewiesen an “ leer und der Wert des Felds „Abgelehnt “ ist „true“ für das angegebene Arbeitselement.

    URL-Format

    Versionierte URL: /api/now/{api_version}/awa/inbox/actions/reject

    Standard-URL: /api/now/awa/inbox/actions/reject

    Unterstützte Anforderungsparameter

    Tabelle : 13. 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
    Tabelle : 14. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 15. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    agent_id Sys_id des Service Desk-Mitarbeiters, der in der Benutzertabelle [sys_user] aufgeführt ist.

    Datentyp: Zeichenfolge
    „reject_reason_id“. Sys_id eines Ablehnungsgrunds für diesen Servicekanal. Gründe sind in der Tabelle „Ablehnungsgründe“ [awa_reject_reason] aufgeführt.

    Datentyp: Zeichenfolge
    work_item_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

    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 : 16. Anforderungskopfzeilen
    Kopfzeile Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/json oder application/xml.

    Standard: application/json
    Tabelle : 17. 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 : 18. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Ungültige Anforderung.
    Mögliche Gründe:
    • Agent-ID fehlt.
    • Arbeitselement-ID fehlt.
    • Fehlende ID des Ablehnungsgrunds.
    • Arbeitselement ist einem anderen Service Desk-Mitarbeiter zugewiesen.
    • Arbeitselement befindet sich nicht im Akzeptanzstatus „Ausstehend“.
    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.
    Mögliche Gründe:
    • Falsche Agent-ID: Für den angegebenen Anwender ist kein Datensatz vorhanden.
    • Falsche ID des Ablehnungsgrunds: Für den angegebenen Ablehnungsgrund ist kein Datensatz vorhanden.
    • Falsche Arbeitselement-ID: Für das angegebene Arbeitselement ist kein Datensatz vorhanden.
    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
    agent_id Sys_id des Service Desk-Mitarbeiters, der in der Benutzertabelle [sys_user] aufgeführt ist.

    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.
    Mögliche Werte:
    • Fehlende Agent-ID : agent_id wurde im Anforderungstext nicht angegeben.
    • Fehlende Element-ID für Ablehnungsgrund : reject_reason_id wurde im Anforderungstext nicht angegeben.
    • Fehlende Arbeitselement-ID : work_item_id wurde im Anforderungstext nicht angegeben.
    • Es gibt keinen Datensatz für awa_reject_reason: <reason_sys_id> – Die im Anforderungstext angegebene reject_reason_id hat keinen übereinstimmenden Datensatz in der Tabelle „Ablehnungsgründe“ [awa_reject_reason].
    • Es gibt keinen Datensatz für awa_work_item: <work_item_sys_id> – Die im Anforderungstext angegebene work_item_id hat keinen übereinstimmenden Datensatz in der Tabelle „AWA-Arbeitselement“ [awa_work_item].
    • Es gibt keinen Datensatz für sys_user: <agent_sys_id> – Der im Anforderungstext angegebene agent_id hat keinen übereinstimmenden Datensatz in der Benutzertabelle [sys_user].
    • Arbeitselement befindet sich nicht im Akzeptanzstatus „Ausstehend“ –Das im Anforderungstext angegebene Arbeitselement befindet sich in einem anderen Status als „Akzeptanz steht aus“.

    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
    „reject_reason_id“. Sys_id eines Ablehnungsgrunds für diesen Servicekanal. Gründe sind in der Tabelle „Ablehnungsgründe“ [awa_reject_reason] aufgeführt.

    Datentyp: Zeichenfolge
    work_item_id Sys_id des Arbeitselements, das in der Tabelle „AWA-Arbeitselement“ [awa_work_item] aufgeführt ist.

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie Sie ein zugewiesenes Arbeitselement mit dem Grund „nicht meine Kompetenz“ ablehnen.

    curl "https://instance.service-now.com/api/now/awa/inbox/actions/reject" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
    \"agent_id\":\"46c9e158a9fe198101d44d0d22cb640d\",
    \"work_item_id\":\"3ed5df4d87cf01101ae365b83cbb35af\",
    \"reject_reason_id\":\"31e3fa29b38023002e7b6e5f26a8dc17\"
}" \
--user 'username':'password'

    Bei einer erfolgreichen Ausgabe werden dasselbe Arbeitselement, derselbe Ablehnungsgrund und dieselbe Benutzer-ID angezeigt, die im Anforderungstext angegeben sind. Das in der Tabelle „AWA-Arbeitselement“ [awa_work_item] angegebene Arbeitselement weist ein leeres Feld Zugewiesen an auf, und der Wert des Felds Abgelehnt ist true.

    {
  "result": {
    "work_item_id": "3ed5df4d87cf01101ae365b83cbb35af",
    "reject_reason_id": "31e3fa29b38023002e7b6e5f26a8dc17",
    "agent_id": "46c9e158a9fe198101d44d0d22cb640d"
  }
}