Arbeits-API für AWA-Angebot
Die AWA-Angebotsarbeits- API bietet einen Endpunkt zum Zuweisen oder Übertragen von Arbeitselementen an Service Desk-Mitarbeiter.
Diese API ist für die Verwendung mit Contact Center as Service-Integrationen (CCAAS) vorgesehen, bei denen die Weiterleitungs- und Zuweisungsentscheidung im externen CCAAS-System getroffen wird. Mit dieser API kann einem Service Desk-Mitarbeiter in ServiceNow Mitarbeiterbereich eine Posteingangskarte als Benachrichtigung angezeigt werden, dass er das Arbeitselement annimmt.
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.
Weitere Informationen zu AWAfinden Sie unter Erweiterte Arbeitszuweisung.
AWA-Angebotsarbeit – POST /now/awa/documents/{document_table}/{document_sys_id}/offer
Weist Service Desk-Mitarbeitern Arbeitselemente zu oder überträgt sie.
Ein Arbeitselement ist ein einzelnes Arbeitselement, das von einem Service Desk-Mitarbeiter AWA vom Typ von Anfang bis Ende bearbeitet wird. Ein Arbeitselement wird basierend auf einem Dokument wie einer Interaktion oder Aufgabe erstellt.
Alle Service Desk-Mitarbeiter, die Arbeitselemente mit dieser API empfangen oder übertragen, müssen über die Rollen „awa_agent“ und „awa_external_user“ verfügen.
URL-Format
URL mit Versionsnummer: /api/now/{api_version}/awa/documents/{document_table}/{document_sys_id}/offer
Standard-URL: /api/now/awa/documents/{document_table}/{document_sys_id}/offer
Unterstützte Anforderungsparameter
| 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 |
| document_table | Name der Tabelle, die dem Dokument zugeordnet ist, z. B. Interaktionstabelle [interaction] oder Aufgabentabelle [task]. Datentyp: Zeichenfolge |
| document_sys_id | Sys_id des Dokuments, das an den Service Desk-Mitarbeiter oder die Warteschlange weitergeleitet werden soll. Datentyp: Zeichenfolge |
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| Zuweisung | Erforderlich für neue Zuweisungen. Objekt mit Informationen zur Zuweisung. Datentyp: Objekt |
| assignment.after_timeout_presence | Sys_id des Anwesenheitsstatus, in den der Service Desk-Mitarbeiter wechselt, wenn der Parameter timeout abläuft. 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 (Anwesenheitsstatus des Service Desk-Mitarbeiters ändert sich nicht). Tabelle: AWA-Anwesenheitsstatus [awa_presence_state] |
| Zuweisung.agent_sys_id | Erforderlich für neue Zuweisungen. Sys_id des verfügbaren Service Desk-Mitarbeiters, der das Arbeitselement erhalten soll. Er muss über die Rollen awa_agent und awa_external_user verfügen. Informationen dazu, wie Sie bestimmen können, ob ein Service Desk-Mitarbeiter verfügbar ist, finden Sie unter Steuerelemente im Posteingang. Datentyp: Zeichenfolge Tabelle: Benutzer [sys_user] |
| assignment.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:
Datentyp: Boolesch Standardwert: wahr |
| Zuweisung.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_assigntrueist. Gültige Werte:
Datentyp: Zeichenfolge Standard: card_only |
| assignment.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:
Datentyp: Boolesch Standardwert: false |
| assignment.offered_on | 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) |
| Zuweisung.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 Standard: Leere Zeichenfolge (keine Zeitbegrenzung). |
| external_segment_id | Externer Bezeichner aus dem CCAAS-System des Anrufsegments, das dem Service Desk-Mitarbeiter angeboten wird Datentyp: Zeichenfolge |
| queue_id | Erforderlich für neue Zuweisungen. Sys_id des Warteschlangendatensatzes oder Warteschlangenbezeichner in einem externen System Wenn eine queue_id aus einem externen System verwendet wird, muss sie dem Feld Anbieterwarteschlangen-ID (external_id) im Datensatz „awa_queue“ zugeordnet werden. Datentyp: Zeichenfolge Tabelle: Warteschlange [awa_queue] |
| Übertragung | Erforderlich für Transferzuweisungen. Objekt mit Informationen zur Übertragung. Wenn für diesen Parameter ein Wert angegeben ist, wird die Zuweisung als Übertragungszuweisung betrachtet. Datentyp: Objekt |
| transfer.source_queue_id | Erforderlich für Transferzuweisungen. Quellwarteschlange, von der aus die Übertragung initiiert wird. Sys_id des Warteschlangendatensatzes oder Warteschlangenbezeichner in einem externen System Wenn eine queue_id aus einem externen System verwendet wird, muss sie dem Feld Anbieterwarteschlangen-ID (external_id) im Datensatz „awa_queue“ zugeordnet werden. Dieser Parameter wird verwendet, um ein Arbeitselement zu erstellen, bevor die Übertragung initiiert wird, wenn kein aktives Arbeitselement gefunden wird. Ermöglicht Übertragungen, wenn die ursprüngliche Interaktion ohne Weiterleitung erstellt wurde, z. B. für ausgehende Anrufe. Datentyp: Zeichenfolge Tabelle: Warteschlange [awa_queue] |
| transfer.target_id | Erforderlich für Transferzuweisungen. Sys_id des Mitarbeiter- oder Warteschlangendatensatzes, an den die Zuweisung übertragen werden soll.
Datentyp: Zeichenfolge |
| transfer.target_type | Erforderlich für Transferzuweisungen. Typ des Datensatzes, an den die Zuweisung übertragen werden soll. Gültige Werte:
Datentyp: Zeichenfolge |
| transfer.transfer_type | Erforderlich für Transferzuweisungen. Typ der Übertragung. Gültige Werte:
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.
| 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 |
| 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.
| 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 Arbeitselement oder der Service Desk-Mitarbeiter-sys_id des angegebenen Dokuments nicht verarbeitet 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 |
|---|---|
| Nachricht | Antwortnachricht mit Informationen über die erfolgreiche oder fehlgeschlagene Zuweisung. Mögliche Werte:
|
| Erfolg | Kennzeichnung, die angibt, ob die Zuweisung erfolgreich ist. Mögliche Werte:
Datentyp: Boolesch |
| work_item | Details zum erstellten oder aktualisierten Arbeitselement. Datentyp: Objekt |
| work_item.display_name | Anzeigename des Dokumentdatensatzes. Datentyp: Zeichenfolge |
| work_item.document_id | Sys_id des Dokumentdatensatzes. Datentyp: Zeichenfolge |
| work_item.document_table | Name der Tabelle, die dem Dokument zugeordnet ist. Datentyp: Zeichenfolge |
| work_item.queue | Sys_id des Warteschlangendatensatzes oder Warteschlangenbezeichner in einem externen System Datentyp: Zeichenfolge Tabelle: Warteschlange [awa_queue] |
| work_item.sys_id | Sys_id des Arbeitselements. Datentyp: Zeichenfolge Tabelle: Arbeitselement [awa_work_item] |
cURL-Anforderung
In diesem Beispiel wird gezeigt, wie einem Service Desk-Mitarbeiter ein Arbeitselement zugewiesen wird.
curl "https://instance.servicenow.com/api/now/awa/documents/interaction/59616aba87bd5210be070d48dabb35e6/offer" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data '{
"external_segment_id": "segment_59616aba87bd5210be070d48dabb35e6",
"queue_id": "92f8942787851210be070d48dabb35fb",
"assignment": {
"agent_sys_id": "0d584509c323120095ccd02422d3ae5b",
"allowed_to_decline": "true",
"enable_auto_assign": "false",
"timeout": 30,
"offered_on":"2024-04-03T23:09:31.000"
}
}'
--user 'username':'password'Die Antwort zeigt, dass das Arbeitselement dem Service Desk-Mitarbeiter erfolgreich zugewiesen wurde. Sie können das Ergebnis im Feld Zugewiesen an des Arbeitselement-Datensatzes [awa_work_item] überprüfen.
{
"result": {
"work_item": {
"display_name": "Interaction: IMS0000221",
"sys_id": "bfa3a27e87bd5210be070d48dabb3588",
"document_id": "59616aba87bd5210be070d48dabb35e6",
"document_table": "interaction",
"queue": "92f8942787851210be070d48dabb35fb"
},
"success": true,
"message": "Manual assignment successfully requested."
}
}