API für aktive Einbindung
Die API für aktive Einbindung bietet einen Endpunkt zum Erstellen von Problemen mit der digitalen Experience.
Diese API ist als anwenderdefinierte REST API mit Skript verfügbar. Erfordert das Plugin „Aktive Einbindung“ (proactive-engagement) und die Rolle sn_pren.experience_issue_create. Diese API gehört zum Namespace sn_pren.
Verwenden Sie die API Aktive Einbindung, um ein Experience-Problem zu erstellen, wenn in der Instanz eines Benutzers ein Problem erkannt wird. Das erstellte Experience-Problem fördert die Interaktion mit dem Benutzer und hilft ihm, das Problem selbst zu lösen.
Um diese API zu verwenden, stellen Sie sicher, dass die folgenden Tabellen mit Datensätzen gefüllt sind:
- Problemregistrierungsvorlage [sn_pren_issue_registry_template]
- Problemregistrierung [sn_pren_issue_registry]
- Lösung [sn_pren_resolution]
- Benachrichtigungsinhalt [sn_pren_notification_content]
- Anbieter [sn_pren_provider]
Weitere Informationen finden Sie unter Proactive Engagement
Aktive Einbindung – CREATE /api/sn_pren/self_remediation/experience_issue/create
Erstellt ein Experience-Problem, wenn am Endpunkt des Anwenders ein Problem erkannt wird. Aktualisiert die Tabelle „Experience-Probleme“ [sn_pren_experience_issue].
URL-Format
Standard-URL: /api/sn_pren/self_remediation/experience_issue/create
Unterstützte Anforderungsparameter
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| Keine |
| Name | Beschreibung |
|---|---|
| endpoint | Erforderlich. Configuration Item (CI) und Benutzerinformationen, die zum Erkennen von Problemdetails verwendet werden. Hinweis: Alle Parameter in diesem Objekt sind optional. Sie müssen mindestens einen Parameter innerhalb des Objekts übergeben, um den Anwender oder das Gerät zu identifizieren.“ Datentyp: Objekt |
| Endpunkt.CI | Sys_id des CI-Geräts, auf dem das Problem erkannt wurde. Datentyp: Zeichenfolge Tabelle: Computer [cmdb_ci_computer] |
| endpoint.email | E-Mail-Adresse des Anwenders, für den das Problem erkannt wurde. Datentyp: Zeichenfolge |
| endpoint.user_id | Sys_id des Anwenders, für den das Problem erkannt wurde. Datentyp: Zeichenfolge Tabelle: Benutzer [sys_user] |
| endpoint.user_name | Anwendername des Anwenders, für den das Problem erkannt wurde. Datentyp: Zeichenfolge Tabelle: Benutzer [sys_user] |
| Experience_ID | Anwenderdefinierte ID, die dem erstellten Problem zugewiesen werden soll. Datentyp: Zahl Standard: Es wird automatisch eine ID generiert. |
| input_parameters | Parameter, die an die Aktion übergeben werden sollen, die auf dem Gerät ausgeführt wird. Die gesendeten Eingabeparameter werden an die konfigurierte Korrekturaktion für die Lösung übergeben, z. B. an einen Subflow, eine Flow-Aktion oder eine CI-Aktion. Datentyp: Objekt |
| input_parameters.process_id | Sys_id des zu beendenden oder neu zu startenden Prozesses. Datentyp: Zeichenfolge |
| Investigative_details | Details, die für eine manuelle Untersuchung nützlich sein könnten, wenn die Lösung zur Effektivität der Stromnutzung fehlschlägt. Die Untersuchungsdetails werden in den Incident kopiert, der als Fallback erstellt wird, wenn die PUE-Lösung fehlschlägt. Datentyp: Objekt |
| Investigative_details.cpu_usage | CPU-Auslastung auf dem Gerät. Datentyp: Zahl (als Zeichenfolge analysiert) |
| Investigative_details.processes_running | Anzahl der auf dem Gerät ausgeführten Prozesse. Datentyp: Zahl (als Zeichenfolge analysiert) |
| Investigative_Details.available_memory | Verfügbarer Arbeitsspeicher auf dem Gerät. Datentyp: Zahl (als Zeichenfolge analysiert) |
| problem_code | Erforderlich. Problemcode, der dem Problem zugeordnet werden soll. Der Problemcode muss in der Instanz verfügbar sein und bereitgestellt werden. Die API gibt einen Fehler zurück, wenn ein leeres oder ungültiges Problem angegeben wird. Datentyp: Zeichenfolge Tabelle: Problemregistrierung [sn_pren_issue_registry] |
| Anbieter | Erforderlich. Eindeutiger Code für den Anbieter Dieser Code muss mit dem Feld provider_code in der Tabelle sn_pren_provider in der Instanz übereinstimmen. 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 |
| Kopfzeile | Beschreibung |
|---|---|
| Content-Type | Datenformat des Anforderungstexts. Unterstützte Typen: application/json oder application/xml. Standard: application/json |
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 | Ein Experience-Problem wurde erfolgreich erstellt. |
| 400 | Ungültige Anforderung. Geben Sie Endpunktdetails an. In der Anforderung wurde ein leeres Objekt endpoint gesendet. |
| 400 | Ungültiger Problemcode. Geben Sie einen gültigen Problemcode an. In der Anforderung wurde ein leerer issue_code gesendet. |
| 400 | Ungültiger Anbieter, geben Sie einen gültigen Anbieter an. In der Anforderung wurde ein leerer Anbieter gesendet. |
| 400 | Ungültiger Problemcode oder Anbieter, geben Sie gültige Details an. Problem kann in der Instanz nicht erkannt werden. Überprüfen Sie die Details issue_code und provider. |
| 400 | Problemcode hat keine richtige Lösung. Im PUE-Framework ist keine gültige Lösung für das identifizierte Problem konfiguriert. |
| 400 | „Anwender“ konnte nicht aus „Endpunktdetails“ aufgelöst werden. Geben Sie gültige Details an. Dieser Fehler wird zurückgegeben, wenn die PUE-Framework-ID den Anwender nicht anhand der angegebenen Endpunktdetails identifizieren kann. |
| 400 | Ein Experience-Problem wird mit dem angegebenen Problemcode für den angegebenen Anwender gelöst. Das angegebene Experience-Problem befindet sich derzeit im Status „In Bearbeitung“ oder „Offen“. |
| 400 | Vorhandenes Experience-Problem mit angegebenem experience_id wird noch ausgeführt oder ist geschlossen. Dieser Fehler tritt auf, wenn ein Experience-Problem in einem Verkettungsszenario auftritt. Zum Beispiel, wenn ein neuer Schlüssel issue_code mit einem vorhandenen experience_idSchlüssel gesendet wird und das frühere Experience-Problem ausgeführt wird oder sich im Status „Geschlossen“ befindet. Das Experience-Problem mit dieser Experience-ID muss sich im Status „action_wait“ befinden, um einen neuen Issue-Code mit der vorherigen Experience-ID zu senden. |
| 400 | Beim Erstellen des Experience-Problems ist ein Fehler aufgetreten. Dies weist auf einen technischen Fehler hin. |
Parameter des Antworttexts (JSON oder XML)
| Name | Beschreibung |
|---|---|
| experienceId | Experience-ID des erstellten Experience-Problems. Wird aus dem Anforderungsparameter experience_id generiert. Wenn der Parameter experience_id nicht übergeben wird, ist die resultierende ID immer die sys_id des erstellten Datensatzes. Tabelle: Experience-Probleme [sn_pren_experience_issue] |
cURL-Anforderung
Im folgenden Beispiel wird ein Experience-Problem für den Benutzer Abel Tuter erstellt. Der Problemcode im Textkörper ermöglicht Aktive Einbindung, die Lösung aus der Problemregistrierungsvorlage zu identifizieren und über Virtual Agent mit dem Endanwender zu interagieren, um ihn bei der Selbstlösung des Problems zu unterstützen.
curl "http://instance.servicenow.com//api/sn_srf/self_remediation/experience_issue/create" \
--request POST \
--header "Accept:application/json" \
--user 'username':'password'
--data “{
"endpoint": {
"CI": "d049b28e936aa1106f98f6db5cba10d5",
"user_id": "62826bf03710200044e0bfc8bcbe5df1",
"user_name": "abel.tuter",
"email": ""
},
"issue_code": "100",
"provider": "sn",
"experience_id": "09ed4830f393739df33",
"input_parameters": {
"process_id": "10644"
},
"investigative_details": {
"cpu usage": "78%",
"processes running": "35",
"available memory": "23%"
}
}”\
Der Antworttext gibt die Experience-ID zurück, die angibt, dass das Problem erfolgreich erstellt wurde.
{
"result": {
"experience_id": “09ed4830f393739df33”
}
}