Proactive Engagement API

  • Rversion finale: Australia
  • Mis à jour 12 mars 2026
  • 4 minutes de lecture

    • 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

    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

    Tableau 1. Path parameters
    Name Description
    None
    Tableau 2. Query parameters
    Name Description
    None
    Tableau 3. Request body parameters (XML or JSON)
    Name Description
    endpoint Required. Configuration item (CI) and user information used to detect issue details.
    Remarque :
    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": "String",
  "email": "String",
  "user_id": "String",
  "user_name": "String"
}
    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": "String"
}
    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": "String",
  "processes_running": "String",
  "available_memory": "String"
  }
    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.

    Tableau 4. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Tableau 5. Response headers
    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”
  } 
}