API für AWA-Posteingangsaktionen

  • Freigeben Version: Xanadu
  • Aktualisiert 1. August 2024
  • 8 Minuten Lesedauer
  • Die AWA-Posteingangsaktionen- API bietet Endpunkte, um ein Arbeitselement im Namen eines Service Desk-Mitarbeiters anzunehmen 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 Erweiterte Arbeitszuweisung.

    AWA-Posteingangsaktionen – GET /awa/inbox/actions/reject_reasons/{channel_id}

    Ruft die Ablehnungsgründe für Arbeitselemente für einen angegebenen Servicekanal ab.

    URL-Format

    URL mit Versionsnummer: /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. Informationen hierzu 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 „Erweiterte Arbeitszuweisung“ (com.glide.awa) installiert ist. Weitere Informationen finden Sie unter Mit der erweiterten Arbeitszuweisung 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.

    Parameter des Antworttexts (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 sind.

    Datentyp: Zahl

    Wert Wert des Felds „Ablehnungsgrund“, das in der Datenbank gespeichert ist.

    Datentyp: Zeichenfolge

    Sys_id Sys_id eines Ablehnungsgrunds für diesen Servicekanal. Die 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 Servicekanal Chat 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 im Namen eines Service Desk-Mitarbeiters ein Arbeitselement im Status „ Akzeptanz ausstehend “.

    URL-Format

    URL mit Versionsnummer: /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 in der Benutzertabelle [sys_user] aufgeführten Agents.

    Datentyp: Zeichenfolge

    work_item_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

    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:
    • Fehlende Agent-ID.
    • Fehlende Arbeitselement-ID.
    • Das Arbeitselement ist einem anderen Service Desk-Mitarbeiter zugewiesen.
    • Das Arbeitselement weist nicht den Status „Akzeptanz ausstehend“ auf.
    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.
    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
    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 mit dem Namen im Feld documentTable.

    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.
    Mögliche Werte:
    • Fehlende Agent-ID: agent_id wurde nicht im Anforderungstext angegeben.
    • Fehlende Arbeitselement-ID: work_item_id wurde im Anforderungstext nicht angegeben.
    • Arbeitselement ist einem anderen Service Desk-Mitarbeiter zugewiesen: Das angegebene Arbeitselement ist dem angegebenen Service Desk-Mitarbeiter nicht zugewiesen.
    • Falsche Arbeitselement-ID : Das im Anforderungstext angegebene Arbeitselement ist ungenau oder nicht vorhanden.
    • Arbeitselement befindet sich nicht im Status „Akzeptanz ausstehend“ : Das im Anforderungstext bereitgestellte Arbeitselement weist einen anderen Status als „Akzeptanz ausstehend“auf.

    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

    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 im Namen eines Service Desk-Mitarbeiters ein Arbeitselement im Status „ Akzeptanz steht aus“ ab. Bei Erfolg ist das Feld Zugewiesen an leer und der Wert des Felds Abgelehnt ist wahr für das angegebene Arbeitselement.

    URL-Format

    URL mit Versionsnummer: /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 in der Benutzertabelle [sys_user] aufgeführten Agents.

    Datentyp: Zeichenfolge

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

    Datentyp: Zeichenfolge

    work_item_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

    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:
    • Fehlende Agent-ID.
    • Fehlende Arbeitselement-ID.
    • Ablehnungsgrund-ID fehlt.
    • Das Arbeitselement ist einem anderen Service Desk-Mitarbeiter zugewiesen.
    • Das Arbeitselement weist nicht den Status „Akzeptanz ausstehend“ auf.
    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.
    Mögliche Gründe:
    • Falsche Agent-ID: Für den angegebenen Anwender ist kein Datensatz vorhanden.
    • Falsche Ablehnungsgrund-ID: 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.

    Parameter des Antworttexts (JSON oder XML)

    Name Beschreibung
    agent_id Sys_id des in der Benutzertabelle [sys_user] aufgeführten Agents.

    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.
    Mögliche Werte:
    • Fehlende Agent-ID : agent_id wurde im Anforderungstext nicht angegeben.
    • Fehlende Element-ID für Ablehnungsgrundreject_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> – Der 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> – Der 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 Status „Akzeptanz ausstehend“: Das im Anforderungstext bereitgestellte Arbeitselement weist einen anderen Status als „Akzeptanz ausstehend“auf.

    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

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

    Datentyp: Zeichenfolge

    work_item_id Sys_id des in der Tabelle „AWA-Arbeitselement“ [awa_work_item] aufgeführten Arbeitselements.

    Datentyp: Zeichenfolge

    Das folgende Beispiel zeigt, wie Sie ein zugewiesenes Arbeitselement mit dem Grund „not my skill“ (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, der Ablehnungsgrund und die Anwender-ID wie im Anforderungstext angezeigt. Das in der Tabelle „AWA-Arbeitselement“ [awa_work_item] angegebene Arbeitselement hat ein leeres Feld Zugewiesen an, und der Wert des Felds Abgelehnt ist wahr.

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