{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":527,"path":"api-reference/rest-apis/proactive-engagement-api.md","title":"Proactive Engagement API","bundle":null,"doc_type":null,"release":"australia","body":"\n# Proactive Engagement API\n\nThe Proactive Engagement API provides an endpoint for creating digital experience issues.\n\nThis 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.\n\nUse 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.\n\nTo use this API, ensure the following tables are populated with records:\n\n-   Issue Registry Template \\[sn\\_pren\\_issue\\_registry\\_template\\]\n-   Issue Registry \\[sn\\_pren\\_issue\\_registry\\]\n-   Resolution \\[sn\\_pren\\_resolution\\]\n-   Notification Content \\[sn\\_pren\\_notification\\_content\\]\n-   Provider \\[sn\\_pren\\_provider\\]\n\nFor more information, see [Proactive Engagement](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-service-management/proactive-engagement-landing-page.md)\n\n**Parent Topic:**[REST API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/api-rest.md)\n\n## Proactive Engagement - CREATE /api/sn\\_pren/self\\_remediation/experience\\_issue/create\n\nCreates an experience issue when an issue is detected on the user's endpoint. Updates the Experience Issues \\[sn\\_pren\\_experience\\_issue\\] table.\n\n### URL format\n\nDefault URL: `/api/sn_pren/self_remediation/experience_issue/create`\n\n### Supported request parameters\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n|Name|Description|\n|----|-----------|\n|None| |\n\n<table class=\"rest_api_request_body\"><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nendpoint\n\n</td><td>\n\nRequired. 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.\"\n\nData type: Object\n\n```\n\"endpoint\": {\n  \"CI\": \"String\",\n  \"email\": \"String\",\n  \"user_id\": \"String\",\n  \"user_name\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\nendpoint.CI\n\n</td><td>\n\nSys\\_id of the CI device on which the issue was detected.Data type: String\n\nTable: Computer \\[cmdb\\_ci\\_computer\\]\n\n</td></tr><tr><td>\n\nendpoint.email\n\n</td><td>\n\nEmail address of the user for whom the issue was detected.Data type: String\n\n</td></tr><tr><td>\n\nendpoint.user\\_id\n\n</td><td>\n\nSys\\_id of the user for whom the issue was detected.Data type: String\n\nTable: User \\[sys\\_user\\]\n\n</td></tr><tr><td>\n\nendpoint.user\\_name\n\n</td><td>\n\nUser name of the user for whom the issue was detected.Data type: String\n\nTable: User \\[sys\\_user\\]\n\n</td></tr><tr><td>\n\nexperience\\_id\n\n</td><td>\n\nUser-defined ID to assign to the created issue.Data type: Number\n\nDefault: An ID is automatically generated.\n\n</td></tr><tr><td>\n\ninput\\_parameters\n\n</td><td>\n\nParameters 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\n\n```\n\"input_parameters\": {\n  \"process_id\": \"String\"\n}\n```\n\n</td></tr><tr><td>\n\ninput\\_parameters.process\\_id\n\n</td><td>\n\nSys\\_id of the process to terminate or restart. Data type: String\n\n</td></tr><tr><td>\n\ninvestigative\\_details\n\n</td><td>\n\nDetails 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\n\n```\n\"investigative_details\": {\n  \"cpu_usage\": \"String\",\n  \"processes_running\": \"String\",\n  \"available_memory\": \"String\"\n  }\n```\n\n</td></tr><tr><td>\n\ninvestigative\\_details.cpu\\_usage\n\n</td><td>\n\nCPU usage on the device. Data type: Number \\(parsed as a string\\)\n\n</td></tr><tr><td>\n\ninvestigative\\_details.processes\\_running\n\n</td><td>\n\nNumber of processes running on the device.Data type: Number \\(parsed as a string\\)\n\n</td></tr><tr><td>\n\ninvestigative\\_details.available\\_memory\n\n</td><td>\n\nAvailable memory on the device.Data type: Number \\(parsed as a string\\)\n\n</td></tr><tr><td>\n\nissue\\_code\n\n</td><td>\n\nRequired. 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\n\nTable: Issue Registry \\[sn\\_pren\\_issue\\_registry\\]\n\n</td></tr><tr><td>\n\nprovider\n\n</td><td>\n\nRequired. 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\n\n</td></tr></tbody>\n</table>### Headers\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table class=\"rest_api_request_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nAccept\n\n</td><td id=\"accept-entry-RESTAPI\">\n\nData format of the response body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table><table class=\"rest_api_response_headers\"><thead><tr><th>\n\nHeader\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nContent-Type\n\n</td><td id=\"content_type-entry-RESTAPI\">\n\nData format of the request body. Supported types: **application/json** or **application/xml**. Default: **application/json**\n\n</td></tr></tbody>\n</table>### Status codes\n\nThe 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-api-explorer/c_RESTAPI.md).\n\n<table id=\"table_wrm_33x_4zb\"><thead><tr><th>\n\nStatus code\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\n200\n\n</td><td>\n\nAn experience issue was created successfully.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nInvalid request. Provide endpoint details. An empty **endpoint** object was sent in the request.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nInvalid issue code, please provide a valid issue code. An empty **issue\\_code** was sent in the request.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nInvalid provider, please provide a valid provider. An empty provider was sent in the request.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nInvalid issue code or provider, please provide valid details. Issue can't be detected in the instance. Verify **issue\\_code** and **provider** details.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nIssue code does not have a proper resolution. A valid resolution is not configured in the PUE framework for the issue identified.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nCould 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.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nAn 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.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nExisting 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.\n\nThe experience issue with this experience\\_id must be in action\\_wait state to send a new issue\\_code with the previous experience\\_id.\n\n</td></tr><tr><td>\n\n400\n\n</td><td>\n\nError occurred while creating experience issue. This indicates a technical error.\n\n</td></tr></tbody>\n</table>### Response body parameters \\(JSON or XML\\)\n\n<table><thead><tr><th>\n\nName\n\n</th><th>\n\nDescription\n\n</th></tr></thead><tbody><tr><td>\n\nexperienceId\n\n</td><td>\n\nExperience 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.\n\nTable: Experience Issues \\[sn\\_pren\\_experience\\_issue\\]\n\n</td></tr></tbody>\n</table>### cURL request\n\nThe 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.\n\n```\ncurl  \"http://instance.servicenow.com//api/sn_srf/self_remediation/experience_issue/create\" \\\n--request POST \\\n--header \"Accept:application/json\" \\\n--user 'username':'password'\n--data “{\n  \"endpoint\": {\n    \"CI\": \"d049b28e936aa1106f98f6db5cba10d5\",\n    \"user_id\": \"62826bf03710200044e0bfc8bcbe5df1\",\n    \"user_name\": \"abel.tuter\",\n    \"email\": \"\"\n  },\n  \"issue_code\": \"100\",\n  \"provider\": \"sn\",\n  \"experience_id\": \"09ed4830f393739df33\",\n  \"input_parameters\": {\n    \"process_id\": \"10644\"\n  },\n  \"investigative_details\": {\n    \"cpu usage\": \"78%\",\n    \"processes running\": \"35\",\n    \"available memory\": \"23%\"\n  }\n}”\\\n\n```\n\nThe response body returns the experience ID, indicating that the issue creation was successful.\n\n```\n{ \n  \"result\": { \n    \"experience_id\": “09ed4830f393739df33”\n  } \n}\n```\n\n"}}