AgentNowHandler - Scoped

  • Release version: Yokohama
  • Updated January 30, 2025
  • 2 minutes to read

    • The AgentNowHandler script include provides methods that enable running check definitions on demand, checking the status of on demand executions and test check executions and for stopping background checks that were executed on demand.

    This script include requires the Agent Client Collector Framework (sn_agent) store application and is provided within the sn_agent namespace. For more information, refer to Agent Client Collector.

    For the REST API solution, refer to Agent Client Collector API.

    AgentNowHandler - AgentNowHandler()

    Creates an AgentNowHandler instance.

    Table 1. Parameters
    Name Type Description
    None

    The following example shows how to initialize AgentNowHandler.

    var handler = new sn_agent.AgentNowHandler();

    AgentNowHandler - getRequestStatus(String requestId)

    Gets status of the request with the given ID.

    Table 2. Parameters
    Name Type Description
    requestId String A check request ID generated by calling the runCheckForCis() method.
    Table 3. Returns
    Properties Description
    Object Status of the request and any applicable error message.
    status Request status.
    Possible values:
    • done – Check is successful.
    • failure – Check has failed. See error message for details.
    • mid_flow – Request output is being handled by the MID server.
    • processing – Check is in progress.
    • timeout – Check processing exceeded time limit set in the runCheckForCis() method.

    Data type: String
    err_msg Error message if any.
    Possible values:
    • No agents found for relevant CIs.
    • No background check request with given ID.
    • No request with given ID.
    • No test result with given ID.
    • Request timeout.

    Data type: String

    The following example shows how to get the status of a request.

    var handler = new sn_agent.AgentNowHandler();
var check = {checkDefId: "158279505372b30034b8ddeeff7b1270"};
var computerGr = new GlideRecord("cmdb_ci_computer");
computerGr.query();
var requestId = handler.runCheckForCis(computerGr, check, 0, 60);

var reqStatusJson = handler.getRequestStatus(requestId);
gs.info(JSON.stringify(reqStatusJson));

    AgentNowHandler - getTestResultStatus(String testResultId)

    Gets the test check status of the given test result.

    Table 4. Parameters
    Name Type Description
    testResultId String A test result ID generated by creating a test check request.
    Table 5. Returns
    Properties Description
    status Status of the test results.
    Possible values:
    • 0: Pending
    • 1: In progress
    • 2: Complete
    • 3: No test result with given ID

    Data type: String
    output Output describing the status.

    Data type: String

    The following example shows how get result status of a completed test check request.

    var testCheckStatusJson = handler.getTestResultStatus("testResultId");
gs.info(JSON.stringify(testCheckStatusJson));

    AgentNowHandler - runCheckForCis(Object cis, Object check, Number priority, Number timeout)

    Runs a check against the given configuration item.

    Table 6. Parameters
    Name Type Description
    cis GlideRecord GlideRecord of any CMDB table (any application, host, or agent) that the check is working against.
    check Object Check ID and optional check parameters. 
    "check": {
  "checkDefId": "String",
  "params": {Object}
}
    check.checkDefId String Sys_id of a check definition in the Check Definitions [sn_agent_check_def] table.
    check.params Object Optional. Map of parameter names and values. These settings can be used to override the parameter records of the check definition and its specified values. 
    "params": {
  "<parameter name>": "String"
}
    priority Number Priority of the request to be set on the ECC queue.
    Possible values:
    • 0: interactive
    • 1: expedited
    • 2: standard
    timeout Number Value of the timeout for the request in seconds.
    Table 7. Returns
    Type Description
    String Sys_id of the generated background check request.

    The following example shows how to run a background check and get its request ID.

    var handler = new sn_agent.AgentNowHandler();
var check = {checkDefId: "028fcd5067c80010b7b72dbd2685ef4f"};
var computerGr = new GlideRecord("cmdb_ci_computer");
computerGr.query();
var requestId = handler.runCheckForCis(computerGr, check, 0, 60);

gs.info(requestId);

    Output:

    b9cf14aedb5e30106f4810284b961990

    AgentNowHandler - stopBackgroundCheck(String requestId)

    Stops a background check.

    To start a background check, use the runCheckForCis() method.

    Table 8. Parameters
    Name Type Description
    requestId String The ID of a background check request generated by calling the runCheckForCis() method.
    Table 9. Returns
    Type Description
    None

    The following example shows how stop executing a background check.

    handler.stopBackgroundCheck(backRequestId);