API für AWA-Posteingangsaktionen

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 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}

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

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    Name Beschreibung
    api_version Optional. Version des Endpunkts, auf den zugegriffen werden soll. Zum Beispiel v1 oder v2. Geben Sie diesen Wert nur an, um eine andere Endpunktversion als die neueste zu verwenden.

    Datentyp: Zeichenfolge
    channel_id Sys_id eines Servicekanals.

    Datentyp: Zeichenfolge

    Tabelle: Servicekanäle [awa_service_channel]
    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-Antwortcodes der REST-API.

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    400 Fehlerhafte Anforderung. Ein fehlerhafter Anforderungstyp oder eine falsch formatierte Anforderung wurde erkannt.
    401 Nicht autorisiert. Die Anmeldeinformationen sind falsch oder wurden nicht übergeben.
    403 Unzulässig.
    Mögliche Gründe:
    • Der Benutzer verfügt nicht über die Rolle awa_integration_user.
    • Der Wert der Eigenschaft „glide.awa.enabled“ ist nicht „ true“. Diese Eigenschaft wird in der Tabelle „Systemeigenschaft“ [sys_property] aufgeführt, wenn das Plugin „Erweiterte Arbeitszuweisung“ (com.glide.awa) installiert ist. Weitere Informationen finden Sie unter Mit der erweiterten Arbeitszuweisung installierte Komponenten.
    404 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.

    Datentyp: Zeichenfolge

    Tabelle: Ablehnungsgründe [awa_reject_reason]

    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

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

    Unterstützte Anforderungsparameter

    Tabelle : 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 aufgeführten Agents.

    Datentyp: Zeichenfolge

    Tabelle: Benutzer [sys_user]
    work_item_id Sys_id des Arbeitselements.
    Das Arbeitselement muss die folgenden Kriterien erfüllen:
    • Das Arbeitselement muss dem angegebenen Service Desk-Mitarbeiter zugewiesen werden.
    • Das Arbeitselement muss sich im Status „Akzeptanz ausstehend“ befinden.

    Datentyp: Zeichenfolge

    Tabelle: AWA-Arbeitselement [awa_work_item]

    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-Antwortcodes der 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.

    Datentyp: Zeichenfolge

    Tabelle: In der im Feld documentTable identifizierten Tabelle.
    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

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

    Unterstützte Anforderungsparameter

    Tabelle : 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 aufgeführten Agents.

    Datentyp: Zeichenfolge

    Tabelle: Benutzer [sys_user]
    „reject_reason_id“ Sys_id eines Ablehnungsgrunds für diesen Servicekanal.

    Datentyp: Zeichenfolge

    Tabelle: Ablehnungsgründe [awa_reject_reason]
    work_item_id Sys_id des Arbeitselements.
    Das Arbeitselement muss die folgenden Kriterien erfüllen:
    • Das Arbeitselement muss dem angegebenen Service Desk-Mitarbeiter zugewiesen werden.
    • Das Arbeitselement muss sich im Status „Akzeptanz ausstehend“ befinden.

    Datentyp: Zeichenfolge

    Tabelle: AWA-Arbeitselement [awa_work_item]

    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-Antwortcodes der 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 aufgeführten Agents.

    Datentyp: Zeichenfolge

    Tabelle: Benutzer [sys_user]
    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 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> – 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> – Die Person agent_id, die im Anforderungstext angegeben ist, hat keinen übereinstimmenden Datensatz in der Tabelle „Benutzer“ [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.

    Datentyp: Zeichenfolge

    Tabelle: Ablehnungsgründe [awa_reject_reason]
    work_item_id Sys_id des 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"
  }
}