Proactive Engagement API
The Proactive Engagement API provides an endpoint for creating digital experience issues.
This API is available as a custom scripted REST API. It requires the Proactive Engagement (proactive-engagement) plugin and sn_pren.experience_issue_create role. This API belongs to the sn_pren namespace.
Use the Proactive Engagement API to create an experience issue when an issue is detected on a user’s instance. The created experience issue drives engagement with the user and helps them self-resolve the issue.
To use this API, ensure the following tables are populated with records:
- Issue Registry Template [sn_pren_issue_registry_template]
- Issue Registry [sn_pren_issue_registry]
- Resolution [sn_pren_resolution]
- Notification Content [sn_pren_notification_content]
- Provider [sn_pren_provider]
For more information, see Proactive Engagement
Parent Topic:REST API reference
Proactive Engagement - CREATE /api/sn_pren/self_remediation/experience_issue/create
Creates an experience issue when an issue is detected on the user's endpoint. Updates the Experience Issues [sn_pren_experience_issue] table.
URL format
Default URL: /api/sn_pren/self_remediation/experience_issue/create
Supported request parameters
| Name | Description |
|---|---|
| None |
| Name | Description |
|---|---|
| None |
| Name | Description |
|---|---|
| endpoint | Required. Configuration item (CI) and user information used to detect issue details. Note: All parameters within this object are optional. You must pass at least one parameter within the object to identify the user or device." Data type: Object |
| endpoint.CI | Sys\_id of the CI device on which the issue was detected.Data type: String Table: Computer \[cmdb\_ci\_computer\] |
| endpoint.email | Email address of the user for whom the issue was detected.Data type: String |
| endpoint.user\_id | Sys\_id of the user for whom the issue was detected.Data type: String Table: User \[sys\_user\] |
| endpoint.user\_name | User name of the user for whom the issue was detected.Data type: String Table: User \[sys\_user\] |
| experience\_id | User-defined ID to assign to the created issue.Data type: Number Default: An ID is automatically generated. |
| input\_parameters | Parameters to pass to the action that will be executed on the device. The input parameters sent are passed to the configured resolution-remedial action such as a sub flow, flow action, or CI action. Data type: Object |
| input\_parameters.process\_id | Sys\_id of the process to terminate or restart. Data type: String |
| investigative\_details | Details that could be useful for a manual investigation if the Power Usage Effectiveness \(PUE\) resolution fails. The investigative details are copied over to the incident which is created as a fallback when the PUE resolution fails.Data type: Object |
| investigative\_details.cpu\_usage | CPU usage on the device. Data type: Number \(parsed as a string\) |
| investigative\_details.processes\_running | Number of processes running on the device.Data type: Number \(parsed as a string\) |
| investigative\_details.available\_memory | Available memory on the device.Data type: Number \(parsed as a string\) |
| issue\_code | Required. Issue code to associate with the problem. The issue code must be available and deployed in the instance. The API returns an error if an empty or invalid issue is provided.Data type: String Table: Issue Registry \[sn\_pren\_issue\_registry\] |
| provider | Required. Unique code for the provider. This code must match the provider_code field in the sn_pren_provider table on the instance.Data type: String |
Headers
The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.
| Header | Description |
|---|---|
| Accept | Data format of the response body. Supported types: application/json or application/xml. Default: application/json |
| Header | Description |
|---|---|
| Content-Type | Data format of the request body. Supported types: application/json or application/xml. Default: application/json |
Status codes
The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.
| Status code | Description |
|---|---|
| 200 | An experience issue was created successfully. |
| 400 | Invalid request. Provide endpoint details. An empty endpoint object was sent in the request. |
| 400 | Invalid issue code, please provide a valid issue code. An empty issue_code was sent in the request. |
| 400 | Invalid provider, please provide a valid provider. An empty provider was sent in the request. |
| 400 | Invalid issue code or provider, please provide valid details. Issue can't be detected in the instance. Verify issue_code and provider details. |
| 400 | Issue code does not have a proper resolution. A valid resolution is not configured in the PUE framework for the issue identified. |
| 400 | Could not resolve user from endpoint details, please provide valid details. This error is returned if the PUE framework ID is unable to identify the user from the given endpoint details. |
| 400 | An experience issue is being resolved with given issue code for specified user. The specified experience issue is currently in an in-progress or open state. |
| 400 | Existing experience issue with given experience_id is still under execution or is closed. This error occurs when an experience issue is in a chaining scenario. For instance, if a new issue_code key is sent with an existing experience_id, and the earlier experience issue is running or is in closed state. The experience issue with this experience_id must be in action_wait state to send a new issue_code with the previous experience_id. |
| 400 | Error occurred while creating experience issue. This indicates a technical error. |
Response body parameters (JSON or XML)
| Name | Description |
|---|---|
| experienceId | Experience ID of the created experience issue. Generated from the experience_id request parameter.If the experience_id parameter is not passed, the resultant ID is always the sys_id of the created record. Table: Experience Issues [sn_pren_experience_issue] |
cURL request
The following example creates an experience issue for user Abel Tuter. The issue code in the body allows Proactive Engagement to identify the resolution from the Issue Registry Template and engage with the end-user via Virtual Agent to help them self-solve the issue.
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%"
}
}”\
The response body returns the experience ID, indicating that the issue creation was successful.
{
"result": {
"experience_id": “09ed4830f393739df33”
}
}