AWA API für manuelle Zuweisung

  • Freigeben Version: Xanadu
  • Aktualisiert 1. August 2024
  • 6 Minuten Lesedauer

    • Die API für manuelle AWA -Zuweisungen bietet einen Endpunkt für die manuelle Zuweisung von verfügbaren Arbeitselementen an verfügbare Erweiterte Arbeitszuweisung -Service Desk-Mitarbeiter (AWA).

    Ein Arbeitselement ist ein einzelnes Arbeitselement, das von einem Service Desk-Mitarbeiter vom Typ AWA von Anfang bis Ende bearbeitet wird. Beispielsweise ist ein Chat oder ein Fall ein Objekt, das weitergeleitet und an Service Desk-Mitarbeiter zugewiesen werden kann. Weitere Informationen finden Sie unter Erweiterte Arbeitszuweisung.

    Diese API erfordert das Plugin Erweiterte Arbeitszuweisung (com.glide.awa). Zum Aufrufen dieser API benötigen Sie die Rolle awa_manager oder awa_integration_user.

    Manuelle AWA-Zuweisung – POST /now/awa/workitems/{work_item_sys_id}/assignments

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

    Der primäre Anwendungsfall für diesen Endpunkt besteht darin, externe Weiterleitungssysteme für das Weiterleiten von Arbeitselementen zu aktivieren. Wenn Erweiterte Arbeitszuweisung für die Verwendung von externem Routing konfiguriert ist, werden Arbeitselemente in der Warteschlange mithilfe von externem Routing und nicht von AWAzugewiesen. Sie können die Arbeitselementaufgabe zuweisen, indem Sie diesen Endpunkt aufrufen. Weitere Informationen finden Sie unter Externe Weiterleitung verwenden.

    URL-Format

    URL mit Versionsnummer: /now/{api_version}/awa/workitems/{sys_id}/assignments

    Standard-URL: /now/awa/workitems/{sys_id}/assignments

    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
    work_item_sys_id Die sys_id des Arbeitselements, das einem verfügbaren Service Desk-Mitarbeiter zugewiesen werden soll. Befindet sich in der Tabelle „Arbeitselemente“ [awa_work_item].

    Die Zuweisung des Arbeitselements muss aufgehoben werden und es muss sich im Status Akzeptanz steht aus oder In der Warteschlange befinden. Weitere Informationen finden Sie unter Nicht zugewiesene Aufgabenarbeitselemente überprüfen.

    Typ: Zeichenfolge
    Tabelle : 2. Abfrageparameter
    Name Beschreibung
    Keine
    Tabelle : 3. Anforderungstextparameter (XML oder JSON)
    Name Beschreibung
    after_timeout_presence Sys_id des Anwesenheitsstatus, in den der Service Desk-Mitarbeiter wechselt, wenn der Parameter timeout abläuft. Befindet sich in der Tabelle „AWA-Anwesenheitsstatus“ [awa_presence_state].

    Wenn der Parameter timeout nicht übergeben wird, wird dieser Parameter ignoriert.

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

    Datentyp: Zeichenfolge

    Standard: „“ (leere Zeichenfolge)
    agent_sys_id Erforderlich. Sys_id des verfügbaren Service Desk-Mitarbeiters, der das Arbeitselement erhalten soll. Service Desk-Mitarbeiter sind Benutzer mit der Rolle awa_agent in der Tabelle „Benutzer“ [sys_user].

    Informationen dazu, wie Sie bestimmen können, ob ein Service Desk-Mitarbeiter verfügbar ist, finden Sie unter Steuerelemente im Posteingang.

    Datentyp: Zeichenfolge
    allowed_to_decline Kennzeichnung, die angibt, ob Service Desk-Mitarbeiter Arbeitselemente ablehnen dürfen. Wenn dieser Parameter auf „ true“ festgelegt ist, werden auf der Posteingangskarte die Schaltflächen Akzeptieren und Ablehnen angezeigt.
    Gültige Werte (Groß-/Kleinschreibung nicht relevant):
    • true/yes/1: Der Service Desk-Mitarbeiter kann Arbeitselemente ablehnen.
    • false/no/0: Der Service Desk-Mitarbeiter kann Arbeitselemente nicht ablehnen.

    Datentyp: Boolesch

    Standardwert: true
    display_option Anzeigeoption für die Karte und die Registerkarte, wenn ein Arbeitselement automatisch zugewiesen wird.

    Dieser Parameter ist nur gültig, wenn enable_auto_assign als trueübergeben wird.

    Gültige Werte:
    • card_only: Zeigt nur die Karte an.
    • card_and_tab: Zeigt sowohl die Karte als auch die Registerkarte 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 (Groß-/Kleinschreibung nicht relevant):
    • wahr/ja/1: Automatisch akzeptieren.
    • false/no/0: Zulassen, dass Service Desk-Mitarbeiter manuell akzeptieren oder ablehnen.

    Datentyp: Boolesch

    Standardwert: false
    angeboten_am Angebotszeit für Arbeitselement. Die Angebotszeit wird verwendet, um die verbleibende Zeit zu berechnen, die dem Service Desk-Mitarbeiter noch bleibt, um das Arbeitselement im Posteingang anzunehmen. Dies trägt dazu bei, die Diskrepanz zwischen dem Zeitpunkt, zu dem die API-Anforderung verarbeitet wird, und dem Zeitpunkt, zu dem die API-Anforderung durch das Weiterleitungssystem des Drittanbieters aufgerufen wird, 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 durch das externe System synchronisiert bleibt.

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

    Dieser Wert wird im Feld „provided_on“ des Arbeitselements gespeichert.

    Dieser Parameter wird ignoriert, wenn der Parameter timeout nicht übergeben wird.

    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
    Content-Type 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 HTTP-Antwortcodesder REST-API.

    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 der angegebenen Arbeitselement- oder Agent-sys_id nicht übergeben werden.
    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
    Erfolg Kennzeichnung, die angibt, ob die manuelle Zuweisung von Arbeitselementen erfolgreich war.
    Mögliche Werte:
    • „wahr“: Zuweisung des Arbeitselements erfolgreich.
    • „falsch“: Zuweisung des Arbeitselements nicht erfolgreich.

    Datentyp: Boolesch
    Nachricht Antwortnachricht, die eine erfolgreiche Zuweisung oder eine Ausnahme bestätigt.

    Erfolg: „Manuelle Zuweisung erfolgreich angefordert.“

    Ausnahmen:
    • “<work_item_sys_id> ist kein gültiges Arbeitselement“ – Angegebene Arbeitselement-sys_id ist nicht vorhanden.
    • „Anrufer“.<API_caller_sys_id> hat nicht die Rolle „awa_manager“ oder „awa_integration_user“: Der authentifizierte Anwender, der die API-Anforderung sendet, muss entweder über die Rolle „awa_manager“ oder „awa_integration_user“ verfügen.
    • „Arbeitselement<work_item_sys_id> kann nicht zugewiesen werden: Das angegebene Arbeitselement kann nicht zugewiesen werden, da es sich im Status „ Akzeptiert “ oder „ Abgebrochen “ befindet. Weitere Informationen finden Sie unter Arbeitselemente und AWA-Ereignisse überprüfen.
    • “<agent_sys_id> ist kein gültiger Service Desk-Mitarbeiter: Der Service Desk-Mitarbeiter verfügt nicht über die Rolle „awa_agent“.
    • „Arbeitselement“ ist bereits zugewiesen<agent_sys_id> „“: Angegebenes Arbeitselement ist einem anderen Service Desk-Mitarbeiter zugewiesen.
    • „Service Desk-Mitarbeiter ist nicht verfügbar“: Der Service Desk-Mitarbeiter befindet sich in AWA nicht im Status „ Verfügbar “. Weitere Informationen finden Sie unter Posteingangssteuerungenfür Mitarbeiter.
    • „Zeitüberschreitungswert darf nicht negativ sein“ – Der angegebene Zeitüberschreitungswert darf kein negativer Wert sein.
    • “<presence_state_sys_id> ist kein gültiger Anwesenheitsstatus“ – Der angegebene Anwesenheitsstatus „sys_id“ ist in der Tabelle „AWA-Anwesenheitsstatus“ [awa_presence_state] nicht vorhanden.
    • "Angebotene Zeit (<offered_on_timestamp> ) muss das folgende Format aufweisen: jjjj-MM-tt'T'HH:mm:ss.SSS“ – Der angegebene Zeitstempel offered_on 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.“ – Der Zeitstempel von offered_on darf nicht vor dem Zeitpunkt liegen, zu dem die Anforderung gestellt wird.
    • „Zeitstempel nach Zeitüberschreitung (<offered_on_timestamp > ) muss nach der aktuellen Uhrzeit liegen, andernfalls hat der Service Desk-Mitarbeiter keine Zeit, das Arbeitselement anzunehmen.“ – Der Zeitstempel nach dem Hinzufügen des Timeout-Werts zum angegebenen Zeitstempel offered_on muss nach der Zeit liegen, zu der die Anforderung gestellt wurde.
    • “<display_option> ist keine gültige Anzeigeoption“ – Für „display_option“ muss einer der folgenden Werte angegeben werden: „card_only“ oder „card_and_tab“
    • „%s ist kein gültiger boolescher Wert“ – Der angegebene Wert vom Typ „Boolesch“ muss eines der folgenden booleschen Formate aufweisen: „ja“/„nein“, „wahr“/„falsch“, „1“/„0“

    Datentyp: Zeichenfolge

    cURL-Anforderung

    Das folgende Beispiel zeigt, wie Sie einem verfügbaren AWA-Mitarbeiter ein Arbeitselement nur mit den erforderlichen Parametern zuweisen.

    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 die Ergebnisse im Feld Zugewiesen an der Tabelle „Arbeitselemente“ [awa_work_item] überprüfen.

    {
  "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 die Ergebnisse im Feld Zugewiesen an der Tabelle „Arbeitselemente“ [awa_work_item] überprüfen.

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