AWA API für manuelle Zuweisung

  • Freigeben Version: Zurich
  • Aktualisiert 31. Juli 2025
  • 6 Minuten Lesedauer

    • Die Manuelle AWA-Zuweisung Die API bietet einen Endpunkt zum manuellen Zuweisen verfügbarer Arbeitselemente zu verfügbar Erweiterte Arbeitszuweisung(AWA) Service Desk-Mitarbeiter.

    Ein Arbeitselement ist ein einzelnes Arbeitselement, das von einem bearbeitet wird AWA Service 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 Arbeitszuweisung Plugin (com.Glide.awa). Um diese API aufzurufen, benötigen Sie entweder die Rolle Awa_Manager oder Awa_Integration_user.

    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 Arbeitszuweisung Ist 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 der Formular „geskripteter REST-Service“ .

    Unterstützte Anforderungsparameter

    Tabelle : 1. Pfadparameter
    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.

    Die Zuweisung des Arbeitselements muss aufgehoben werden und muss sich im befinden Annahme Ausstehend 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. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    After_timeout_presence SYS_ID des Anwesenheitsstatus, zu dem der Service Desk-Mitarbeiter wechselt, wenn der 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 für den Empfang des Arbeitselements. 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 Bedienelemente für den Posteingang des Service Desk-Mitarbei .

    Datentyp: Zeichenfolge

    Tabelle: Benutzer [sys_user]
    Allowed_to_Decly Kennzeichnung, die angibt, ob Service Desk-Mitarbeiter Arbeitselemente ablehnen dürfen. Wenn dieser Parameter ist Wahr , Auf der Posteingangskarte werden beide angezeigt 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: Boolesch

    Standardwert: 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 es 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: Boolesch

    Standardwert: false
    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 einer 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 es 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 angebotene_on des Arbeitselements gespeichert.

    Dieser Parameter wird ignoriert, wenn der 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 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
    Inhaltstyp 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 REST API-HTTP-Antwortcodes .

    Tabelle : 6. Statuscodes
    Statuscode Beschreibung
    200 Erfolgreich. Die Anforderung wurde erfolgreich verarbeitet.
    401 Nicht autorisiert. Die Anmeldeinformationen 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 Service Desk-Mitarbeiters nicht übergeben werden
    500 Interner Serverfehler. Beim Verarbeiten der Anforderung ist ein unerwarteter Fehler aufgetreten. Der Antworttext enthält Informationen zum Fehler.

    Antworttext-Parameter (JSON oder XML)

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

    Datentyp: Boolesch
    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 bereits <agent_sys_id> 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 Bedienelemente für den Posteingang des Service Desk-Mitarbei .
    • „Zeitüberschreitungswert darf nicht negativ sein“ – angegebener Zeitüberschreitungswert darf kein negativer Wert sein.
    • „<presence_state_sys_id> ist kein gültiger Anwesenheitsstatus“ – die sys_ID des angegebenen Anwesenheitsstatus ist in der Tabelle „AWA-Anwesenheitsstatus“ [Awa_presence_State] nicht vorhanden.
    • „Angebotene Zeit (<offered_on_timestamp>) muss im folgenden Format vorliegen: 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, das Arbeitselement zu akzeptieren“ – bereitgestellt 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 nach dem Hinzufügen des Zeitüberschreitungswerts zum angegebenen 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 einem verfügbaren AWA-Service Desk-Mitarbeiter ein Arbeitselement 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 einem verfügbaren AWA-Service Desk-Mitarbeiter ein Arbeitselement 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."
  }
}