AWA API für manuelle Zuweisung

  • Freigeben Version: Yokohama
  • Aktualisiert 30. Januar 2025
  • 6 Minuten Lesedauer

    • Die Manuelle AWA-Zuweisung Die API stellt einen Endpunkt bereit, um verfügbare Arbeitselemente manuell den verfügbaren zuzuweisen Erweiterte Arbeitszuweisung(AWA) Service Desk-Mitarbeiter.

    Ein Arbeitselement ist eine einzelne Arbeit, die von einem bearbeitet wird AWAService Desk-Mitarbeiter von Start bis Ende. Beispielsweise ist ein Chat oder ein Fall ein Objekt, das weitergeleitet und Service Desk-Mitarbeitern zugewiesen werden kann. Weitere Informationen finden Sie unter Erweiterte Arbeitszuweisung .

    Diese API erfordert Erweiterte ArbeitszuweisungPlugin (com.Glide.awa). Um diese API aufzurufen, müssen Sie entweder über die Rolle „Awa_Manager“ oder „Awa_Integration_user“ verfügen.

    Manuelle AWA-Zuweisung: VERÖFFENTLICHEN SIE /now/Awa/workitems/{work_item_sys_id}/Zuweisungen

    Weist einem verfügbaren Arbeitselement ein verfügbares Arbeitselement zu Erweiterte Arbeitszuweisung(AWA) Service Desk-Mitarbeiter.

    Der primäre Anwendungsfall für diesen Endpunkt besteht darin, externen Weiterleitungssystemen die Weiterleitung von Arbeitselementen zu ermöglichen. Wenn Erweiterte ArbeitszuweisungIst für die Verwendung externer Weiterleitung konfiguriert. Arbeitselemente in der Warteschlange werden mit externer Weiterleitung zugewiesen und nicht AWA. Sie können die Arbeitselementaufgabe zuweisen, indem Sie diesen Endpunkt aufrufen. Weitere Informationen finden Sie unter Externe Weiterleitung verwenden .

    URL-Format

    Versionierte URL: /Now/{api_Version}/Awa/workitems/{sys_ID}/Zuweisungen

    Standard-URL: /Now/awa/workitems/{sys_ID}/Zuweisungen

    Hinweis:
    Verfügbare Versionen werden in angegeben REST-API-Explorer . Für geskriptete REST-APIs gibt es zusätzliche Versionsinformationen auf Geskriptetes REST-Service-Formular .

    Unterstützte Anforderungsparameter

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

    Datentyp: Zeichenfolge
    work_item_sys_id SYS_ID des Arbeitselements, das einem verfügbaren Service Desk-Mitarbeiter zugewiesen werden soll.

    Das Arbeitselement muss nicht zugewiesen sein und sich in befinden Annahme Steht Aus Oder In Warteschlange status. Weitere Informationen finden Sie unter Überprüfen Sie nicht zugewiesene Aufgabenarbeitselemente .

    Datentyp: Zeichenfolge

    Tabelle: Arbeitselemente [Awa_work_item]
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstext-Parameter (XML oder JSON)
    Name Beschreibung
    After_timeout_presence SYS_ID des Anwesenheitsstatus, zu dem der Service Desk-Mitarbeiter wechselt, wenn dies der Fall ist timeoutParameter läuft ab.

    Wenn timeoutParameter wurde nicht übergeben, dieser Parameter wird ignoriert.

    Weitere Informationen zu anwesenheitsstatus finden Sie unter Configure agent presence states.

    Datentyp: Zeichenfolge

    Standard: „“ (leere Zeichenfolge)

    Tabelle: AWA-Anwesenheitsstatus [Awa_presence_State]
    Agent_sys_ID Erforderlich. SYS_ID des verfügbaren Service Desk-Mitarbeiters, der das Arbeitselement empfangen soll. Service Desk-Mitarbeiter sind Anwender mit der Rolle „Awa_Agent“.

    Informationen dazu, wie Sie bestimmen, ob ein Service Desk-Mitarbeiter verfügbar ist, finden Sie unter Steuerungen für Posteingang des Service Desk-Mitarbeiters .

    Datentyp: Zeichenfolge

    Tabelle: Anwender [sys_user]
    Allowed_to_Decly Kennzeichnung, die angibt, ob Service Desk-Mitarbeiter Arbeitselemente ablehnen dürfen. Wenn dieser Parameter ist Wahr , Die Posteingangskarte zeigt beide an Akzeptieren Und Ablehnen Schaltflächen auf der Posteingangskarte.
    Gültige Werte:
    • Wahr/ja/1: Service Desk-Mitarbeiter kann Arbeitselemente ablehnen.
    • Falsch/nein/0: Service Desk-Mitarbeiter kann Arbeitselemente nicht ablehnen.

    Datentyp: Boolescher Wert

    Standard: Wahr
    Display_Option Anzeigeoption für die Karte und Registerkarte, wenn ein Arbeitselement automatisch zugewiesen wird.

    Dieser Parameter ist nur gültig, wenn enable_auto_assignWird übergeben als Wahr .

    Gültige Werte:
    • Card_and_tab: Karte und Registerkarte anzeigen.
    • Card_only: Zeigt nur die Karte an.

    Datentyp: Zeichenfolge

    Standard: Card_only
    Enable_Auto_assign Kennzeichnung, die angibt, ob das Arbeitselement automatisch akzeptiert werden soll oder dem Service Desk-Mitarbeiter ermöglichen soll, das Arbeitselement manuell zu akzeptieren oder abzulehnen.
    Gültige Werte:
    • Wahr/ja/1: Automatisch akzeptieren.
    • Falsch/nein/0: Zulassen, dass Service Desk-Mitarbeiter manuell akzeptieren oder ablehnen.

    Datentyp: Boolescher Wert

    Standard: Falsch
    Angeboten_am Angebotszeit des Arbeitselements. Die Angebotszeit wird verwendet, um die verbleibende Zeit zu berechnen, die dem Service Desk-Mitarbeiter verbleibt, um das Arbeitselement im Posteingang zu akzeptieren. Es hilft, die Diskrepanz zwischen dem Zeitpunkt, zu dem die API-Anforderung verarbeitet wird, und dem Zeitpunkt, zu dem das Weiterleitungssystem der Drittpartei die API-Anforderung aufruft, zu berücksichtigen. Mit diesem Parameter können externe Systeme, die diesen Endpunkt aufrufen, die Angebotszeit des Arbeitselements so konfigurieren, dass sie mit der internen Nachverfolgung des Arbeitselements des externen Systems synchronisiert bleibt.

    Wenn das Arbeitselement beispielsweise am 11:30:30 angeboten wurde, die Zeitüberschreitung 30 Sekunden beträgt und die aktuelle Zeit 11:30:45 ist, zeigt der Countdown-Timer 00:15 an (wie in 15 Sekunden verbleibend).

    Dieser Wert wird im Feld Offered_on des Arbeitselements gespeichert.

    Dieser Parameter wird ignoriert, wenn timeoutParameter wurde nicht übergeben.

    Datentyp: Zeichenfolge

    Format: UTC-Zeitstempel (jjjj-MM-tt'T'HH:mm:ss.SSS)
    Zeitüberschreitung Zeit, die das Arbeitselement im Posteingang des Service Desk-Mitarbeiters verbleibt und darauf wartet, dass der Service Desk-Mitarbeiter die Arbeitszuweisung akzeptiert.

    Datentyp: Zahl

    Einheit: Sekunden

    Header

    Die folgenden Anforderungs- und Antwort-Header gelten nur für diese HTTP-Aktion oder werden auf diese Aktion in einer bestimmten Weise angewendet. Eine Liste der allgemeinen Header, die in der REST-API verwendet werden, finden Sie unter Unterstützte REST-API-Header .

    Tabelle : 4. Anforderungskopfzeilen.
    Header Beschreibung
    Akzeptieren Datenformat des Antworttexts. Unterstützte Typen: application/jsonOder application/xml.

    Standard: application/json
    Inhaltstyp Datenformat des Anforderungstexts. Unterstützte Typen: application/jsonOder application/xml.

    Standard: application/json
    Tabelle : 5. Antwort-Header
    Header 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 REST-API-HTTP-Antwortcodes .

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    401 Nicht autorisiert Die Anwenderanmeldeinformationen sind falsch oder wurden nicht übergeben.
    404 Nicht gefunden. Das angeforderte Element wurde nicht gefunden.
    409 Konflikt. Die Anforderung konnte aufgrund eines Fehlers mit dem angegebenen Arbeitselement oder der sys_ID des Agenten nicht übergeben werden
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Die Antwort enthält zusätzliche Informationen zum Fehler.

    Antworttext-Parameter (JSON oder XML)

    Name Beschreibung
    Erfolg Kennzeichnung, die angibt, ob die manuelle Arbeitselementzuweisung erfolgreich ist.
    Mögliche Werte:
    • Wahr: Zuweisung des Arbeitselements erfolgreich.
    • Falsch: Zuweisung des Arbeitselements nicht erfolgreich.

    Datentyp: Boolescher Wert
    Nachricht Antwortnachricht zur Bestätigung einer erfolgreichen Zuweisung oder einer Ausnahme.

    Erfolg: „Manuelle Zuweisung erfolgreich angefordert.“

    Ausnahmen:
    • „<work_item_sys_id> ist kein gültiges Arbeitselement“ – angegebene sys_ID des Arbeitselements ist nicht vorhanden.
    • „Aufrufer-<API_caller_sys_id> hat nicht die Rolle „Awa_Manager“ oder „Awa_Integration_user“ – der authentifizierte Anwender, der die API-Anforderung stellt, muss entweder die Rolle „Awa_Manager“ oder „Awa_Integration_user“ haben.
    • „Arbeitselement-<work_item_sys_id> kann nicht zugewiesen werden“ – angegebenes Arbeitselement kann nicht zugewiesen werden, da es sich in befindet Akzeptiert Oder Abgebrochen status. Siehe Überprüfen Sie Arbeitselemente und AWA-Ereignisse .
    • „<agent_sys_id> ist kein gültiger Agent“ – Service Desk-Mitarbeiter hat nicht die Rolle „Awa_Agent“.
    • „Arbeitselement ist <agent_sys_id> bereits zugewiesen“ – angegebenes Arbeitselement ist einem anderen Service Desk-Mitarbeiter zugewiesen.
    • „Service Desk-Mitarbeiter ist nicht verfügbar“ – Service Desk-Mitarbeiter befindet sich nicht in Verfügbar status in AWA. Siehe Steuerungen für Posteingang des Service Desk-Mitarbeiters .
    • „Zeitüberschreitungswert darf nicht negativ sein“ – angegebener Zeitüberschreitungswert darf kein negativer Wert sein.
    • „<presence_state_sys_id> ist kein gültiger Anwesenheitsstatus“ – angegebene sys_ID des Anwesenheitsstatus ist in der Tabelle „AWA-Anwesenheitsstatus“ [Awa_presence_State] nicht vorhanden.
    • „Angebotene Zeit (<offered_on_timestamp>) muss das folgende Format haben: jjjj-MM-tt'T'HH:mm:ss.SSS“ – angegeben offered_onDer Zeitstempel muss das angegebene Format aufweisen.
    • „Angebotene Zeit (<offered_on_timestamp >) muss vor der aktuellen Zeit liegen, andernfalls hat der Service Desk-Mitarbeiter mehr Zeit, um das Arbeitselement zu akzeptieren“ – angegeben offered_onDer Zeitstempel darf nicht vor dem Zeitpunkt liegen, zu dem die Anforderung gestellt wird.
    • „Zeitstempel nach Zeitüberschreitung (<offered_on_timestamp >) muss nach der aktuellen Zeit liegen, andernfalls hat der Service Desk-Mitarbeiter keine Zeit, das Arbeitselement zu akzeptieren“ – der Zeitstempel, nachdem der Zeitüberschreitungswert dem angegebenen hinzugefügt wurde offered_onDer Zeitstempel muss nach dem Zeitpunkt liegen, zu dem die Anforderung gestellt wurde.
    • „<display_option> ist keine gültige Anzeigeoption“ – angegebene Display_Option muss einer der folgenden Werte sein: „Card_only“ oder „Card_and_tab“
    • „%s ist kein gültiger boolescher Wert“ – angegebener boolescher Wert muss in einem der folgenden booleschen Formate vorliegen: „ja“/„Nein“, „wahr“/„falsch“, „1“/„0“

    Datentyp: Zeichenfolge

    Curl-Anforderung

    Das folgende Beispiel zeigt, wie ein Arbeitselement einem verfügbaren AWA-Agenten nur mit den erforderlichen Parametern zugewiesen wird.

    curl "https://instance.servicenow.com/api/now/awa/workitems/<work_item_sys_id>/assignments" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{\"agent_sys_id\":\"<agent_sys_id>\"}" \
--user 'username':'password'

    Das Ergebnis zeigt, dass die Aufgabe dem Service Desk-Mitarbeiter erfolgreich zugewiesen wurde. Sie können Ergebnisse in überprüfen Zugewiesen an Feld der Tabelle „Arbeitselemente“ [Awa_work_item].

    {
  "result": {
    "success": true,
    "message": "Manual assignment successfully requested."
  }
}

    Curl-Anforderung

    Das folgende Beispiel zeigt, wie ein Arbeitselement einem verfügbaren AWA-Agenten zugewiesen wird, einschließlich der optionalen Parameter.

    curl "https://instance.servicenow.com/api/now/awa/workitems/<work_item_sys_id>/assignments" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data '{
    "agent_sys_id": "46d44a23a9fe19810012d100cca80666",
    "timeout":"10",
    "offered_on":"2024-04-03T23:09:31.000"
  }'
--user 'username':'password'

    Das Ergebnis zeigt, dass die Aufgabe dem Service Desk-Mitarbeiter erfolgreich zugewiesen wurde. Sie können Ergebnisse in überprüfen Zugewiesen an Feld der Tabelle „Arbeitselemente“ [Awa_work_item].

    {
  "result": {
    "success": true,
    "message": "Manual assignment successfully requested."
  }
}