AustraliaREFERENCE GUIDE

AccCheckDefsAPI - Scoped

ServiceNow documentation·12 min readView source ↗

On this page

AccCheckDefsAPI- Scoped

The AccCheckDefsAPI script include enables managing check definitions and associated parameters.

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

This script include does not have a constructor for creating an instance. Call each method using the AccCheckDefsAPI static class in the following format:

sn_agent.AccCheckDefsAPI.<method>

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

This script include provides methods that enable the following:

Get a specified check definition
Get a list of check definitions
Update checks and check parameters

Parent Topic:Server API reference

AccCheckDefsAPI - getCheck(String checkDefId, Boolean withParams)

Gets a specified check definition with details.

Name

</th><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

checkDefId

</td><td>

String

</td><td>

Sys_id of the check definition listed in the Check Definitions [sn_agent_check_def] table.

</td></tr><tr><td>

withParams

</td><td>

Boolean

</td><td>

Flag that indicates whether existing check parameter details are returned. Information for each standard and secure check parameter is included in a JSON object. Valid values:

true: Return check parameter details.
false: Do not return check parameter details.

Default: False

</td></tr></tbody> </table><table id=“table_al2_2g2_z4b” class=“returns”><thead><tr><th>

Properties

</th><th>

Description

</th></tr></thead><tbody><tr><td>

check

</td><td>

Details of the specified check definition. "check ": { "background": Boolean, "check_group": "String", "check_type": "String", "command": "String", "error": "String", "name": "String", "params": [Array], "plugins": [Array], "proxy_valid": Boolean, "secure_params": [Array], "sys_id": "String", "timeout": Number }

</td></tr><tr><td>

check.background

</td><td>

Flag that indicates whether this check definition is a background check. A background check is a check which the agent starts execution of and doesn’t wait for it to finish running. Valid values:

true: This check definition is a background check.
false: This check definition is not a background check.

Data type: Boolean

</td></tr><tr><td>

check.check_group

</td><td>

Group specified for this check definition. Data type: String

</td></tr><tr><td>

check.check_type

</td><td>

Type of check. Possible values:

Events – Check results are transformed into an Event Management event.
Metrics – Values from the check result are transformed to metrics.

Data type: String

</td></tr><tr><td>

check.command

</td><td>

Command that the Agent Client Collector executes. Data type: String

</td></tr><tr><td>

check.error

</td><td>

Message if there is an error. Null otherwise.Data type: String

</td></tr><tr><td>

check.name

</td><td>

Name of the check. Data type: String

</td></tr><tr><td>

check.params

</td><td>

List of parameter definitions associated with the check definition. These results are only included if the withParams parameter is set to true. "params": [ { "active": Boolean, "default_value": "String", "mandatory": Boolean, "name": "String", "sys_id": "String" } ]

Data type: Array

</td></tr><tr><td>

check.params.active

</td><td>

Flag that indicates whether the check parameter is active. Valid values:

true: The check parameter is active.
false: The check parameter is inactive.

Data type: Boolean

</td></tr><tr><td>

check.params.default_value

</td><td>

Specifies the default value for this check parameter. Data type: String

</td></tr><tr><td>

check.params.mandatory

</td><td>

Flag that indicates whether the check parameter is required. Valid values:

true: The check parameter is required.
false: The check parameter is optional.

Data type: Boolean

</td></tr><tr><td>

check.params.name

</td><td>

Name of the check parameter. Data type: String

</td></tr><tr><td>

check.params.sys_id

</td><td>

Sys_id of the check parameter listed in the Check Secure Parameter Definitions [sn_agent_check_param_def] table. Data type: String

</td></tr><tr><td>

check.plugins

</td><td>

List of Agent Client Collector plugins associated with this check. Data type: Array

</td></tr><tr><td>

check.proxy_valid

</td><td>

Flag that indicates whether the check definition policy is set to work as a proxy. Valid values:

true: This check definition policy is set to work as a proxy.
false: This check definition policy is not set to work as a proxy.

Data type: Boolean

</td></tr><tr><td>

check.secure_params

</td><td>

List of assigned to this check. These results are only included if the withParams parameter is set to true. "secure_params": [ { "active": Boolean, "name": "String", "order": Number, "sys_id": "String" } ]

Data type: Array

</td></tr><tr><td>

check.secure_params.active

</td><td>

Flag that indicates whether the secure parameter is active. Valid values:

true: The secure parameter is active.
false: The secure parameter is inactive.

Data type: Boolean

</td></tr><tr><td>

check.secure_params.name

</td><td>

Name of the secure parameter. Data type: String

</td></tr><tr><td>

check.secure_params.order

</td><td>

Order in which the parameter is sent to the check command/script. Data type: Number

</td></tr><tr><td>

check.secure_params.sys_id

</td><td>

Sys_id of the secure parameter listed in the Check Secure Parameter Definitions [sn_agent_check_secure_param_def] table. Data type: String

</td></tr><tr><td>

check.sys_id

</td><td>

Sys_id of the check definition listed in the Check Definitions [sn_agent_check_def] table. Data type: String

</td></tr><tr><td>

check.timeout

</td><td>

Timeout in seconds. Data type: Number

</td></tr></tbody> </table>The following example shows how to get information for a specified check definition.

var checkDefId = "94436b237f705300f128134f8dfa91a4";
var withParams = true;

var checkDef = sn_agent.AccCheckDefsAPI.getCheck(checkDefId, withParams);

gs.info(JSON.stringify(checkDef, null, 2));

Output:

{
  "check": {
    "name": "app.apache.metrics-apache",
    "command": "metrics-apache-graphite.rb -p {{.labels.params_port}} --path {{.labels.params_path}} -h {{.labels.params_host}}",
    "plugins": [
      "monitoring-plugin-common"
    ],
    "timeout": 60,
    "proxy_valid": true,
    "background": false,
    "check_type": "Metrics",
    "check_group": "Apache",
    "sys_id": "94436b237f705300f128134f8dfa91a4",
    "params": [
      {
        "name": "port",
        "active": true,
        "mandatory": true,
        "default_value": "80",
        "sys_id": "58436b237f705300f128134f8dfa91a8"
      },
      {
        "name": "path",
        "active": true,
        "mandatory": true,
        "default_value": "/server-status?auto",
        "sys_id": "98436b237f705300f128134f8dfa91aa"
      },
      {
        "name": "scheme",
        "active": false,
        "mandatory": false,
        "default_value": null,
        "sys_id": "a4e57a96db3bbb4035305c55dc9619f6"
      },
      {
        "name": "host",
        "active": true,
        "mandatory": true,
        "default_value": "127.0.0.1",
        "sys_id": "d4436b237f705300f128134f8dfa91a6"
      },
      {
        "name": "ssl_secure_connection",
        "active": false,
        "mandatory": false,
        "default_value": null,
        "sys_id": "e3b272c4530100106ffeddeeff7b1275"
      }
    ],
    "secure_params": [
      {
        "name": "cred_user_name",
        "active": true,
        "order": 1,
        "sys_id": "2494cd6e53170010f42cddeeff7b1273"
      },
      {
        "name": "cred_password",
        "active": true,
        "order": 2,
        "sys_id": "35948d6e53170010f42cddeeff7b127f"
      }
    ]
  },
  "error": null
}

AccCheckDefsAPI - getChecksList(String encodedQuery, Number limit, Boolean withParams)

Gets a list of check definitions with details.

See also Checks and policies.

Name

</th><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

encodedQuery

</td><td>

String

</td><td>

An encoded query string to filter the check definition result list. Use null for an unfiltered list of check definitions in the system.

</td></tr><tr><td>

limit

</td><td>

Number

</td><td>

Limits the number of returned records. Set to null to use the default value. Default: 20,000

</td></tr><tr><td>

withParams

</td><td>

Boolean

</td><td>

Flag that indicates whether existing check parameter details are returned. Information for each standard and secure check parameter is included in a JSON object. Valid values:

true: Return check parameter details.
false: Do not return check parameter details.

Default: False

</td></tr></tbody> </table><table id=“table_al2_2g2_z4b” class=“returns”><thead><tr><th>

Properties

</th><th>

Description

</th></tr></thead><tbody><tr><td>

check definitions

</td><td>

List of check definition and details provided as JSON objects. [ { "background": Boolean, "check_group": "String", "check_type": "String", "command": "String", "name": "String", "params": [Array], "plugins": [Array], "proxy_valid": Boolean, "secure_params": [Array], "sys_id": "String", "timeout": Number } ]

Data type: Array

</td></tr><tr><td>

background

</td><td id=“accCkDf-background-desc”>

Flag that indicates whether this check definition is a background check. A background check is a check which the agent starts execution of and doesn’t wait for it to finish running. Valid values:

true: This check definition is a background check.
false: This check definition is not a background check.

Data type: Boolean

</td></tr><tr><td>

check_group

</td><td id=“accCkDf-chkGrp-desc”>

Group specified for this check definition. Data type: String

</td></tr><tr><td>

check_type

</td><td id=“accCkDf-chkTyp-desc”>

Type of check. Possible values:

Events – Check results are transformed into an Event Management event.
Metrics – Values from the check result are transformed to metrics.

Data type: String

</td></tr><tr><td>

command

</td><td id=“accCkDf-command-desc”>

Command that the Agent Client Collector executes. Data type: String

</td></tr><tr><td>

name

</td><td id=“accCkDf-name-desc”>

Name of the check. Data type: String

</td></tr><tr><td>

params

</td><td id=“accCkDf-p-desc”>

Data type: Array

</td></tr><tr><td>

params.active

</td><td id=“accCkDf-p-active-desc”>

Flag that indicates whether the check parameter is active. Valid values:

true: The check parameter is active.
false: The check parameter is inactive.

Data type: Boolean

</td></tr><tr><td>

params.default_value

</td><td id=“accCkDf-p-default-desc”>

Specifies the default value for this check parameter. Data type: String

</td></tr><tr><td>

params.mandatory

</td><td id=“accCkDf-p-mando-desc”>

Flag that indicates whether the check parameter is required. Valid values:

true: The check parameter is required.
false: The check parameter is optional.

Data type: Boolean

</td></tr><tr><td>

params.name

</td><td id=“accCkDf-p-name-desc”>

Name of the check parameter. Data type: String

</td></tr><tr><td>

params.sys_id

</td><td id=“accCkDf-p-id-desc”>

Sys_id of the check parameter listed in the Check Secure Parameter Definitions [sn_agent_check_param_def] table. Data type: String

</td></tr><tr><td>

plugins

</td><td id=“accCkDf-plugins-desc”>

List of Agent Client Collector plugins associated with this check. Data type: Array

</td></tr><tr><td>

proxy_valid

</td><td id=“accCkDf-proxy-desc”>

Flag that indicates whether the check definition policy is set to work as a proxy. Valid values:

true: This check definition policy is set to work as a proxy.
false: This check definition policy is not set to work as a proxy.

Data type: Boolean

</td></tr><tr><td>

secure_params

</td><td id=“accCkDf-sp-desc”>

Data type: Array

</td></tr><tr><td>

secure_params.active

</td><td id=“accCkDf-sp-active-desc”>

Flag that indicates whether the secure parameter is active. Valid values:

true: The secure parameter is active.
false: The secure parameter is inactive.

Data type: Boolean

</td></tr><tr><td>

secure_params.name

</td><td id=“accCkDf-sp-name-desc”>

Name of the secure parameter. Data type: String

</td></tr><tr><td>

secure_params.order

</td><td id=“accCkDf-sp-order-desc”>

Order in which the parameter is sent to the check command/script. Data type: Number

</td></tr><tr><td>

secure_params.sys_id

</td><td id=“accCkDf-sp-id-desc”>

Sys_id of the secure parameter listed in the Check Secure Parameter Definitions [sn_agent_check_secure_param_def] table. Data type: String

</td></tr><tr><td>

sys_id

</td><td id=“accCkDf-id-desc”>

Sys_id of the check definition listed in the Check Definitions [sn_agent_check_def] table. Data type: String

</td></tr><tr><td>

timeout

</td><td id=“accCkDf-timeout-desc”>

Timeout in seconds. Data type: Number

</td></tr></tbody> </table>The following example shows how to retrieve a list of two check definitions with parameter values.

var encQuery = "nameSTARTSWITHchecks_";
var limit = 2;
var withParams = true;

var checkDefs = sn_agent.AccCheckDefsAPI.getChecksList(encQuery, limit, withParams);

gs.info(JSON.stringify(checkDefs, null, 2));

Output:

[
  {
    "name": "checks_api_test",
    "command": "echo hello",
    "plugins": [],
    "timeout": 9,
    "proxy_valid": true,
    "background": false,
    "check_type": "TestCheck",
    "check_group": "computer",
    "sys_id": "7f1f9026dba530106f4810284b96194f",
    "params": [],
    "secure_params": [
      {
        "name": "check_api_test_check_secure_param2",
        "active": true,
        "order": 2,
        "sys_id": "2d30a066dba530106f4810284b9619c1"
      },
      {
        "name": "check_api_test_check_secure_param1",
        "active": true,
        "order": 100,
        "sys_id": "4c20a066dba530106f4810284b9619a8"
      }
    ]
  },
  {
    "name": "checks_api_test222",
    "command": "echo hello1212121",
    "plugins": [],
    "timeout": 60,
    "proxy_valid": true,
    "background": false,
    "check_type": "TestCheck",
    "check_group": "computer",
    "sys_id": "99e12466dba530106f4810284b961976",
    "params": [
      {
        "name": "check_api_test_check_param_222",
        "active": true,
        "mandatory": false,
        "default_value": "test_test_test",
        "sys_id": "44026466dba530106f4810284b9619b2"
      }
    ],
    "secure_params": []
  }
]

AccCheckDefsAPI - updateCheck(String checkDefId, Object updateJson)

Enables changing one or more field values of a specified check definition.

AccCheckDefsAPI - updateCheckParam(String checkDefParamId, Object updateJson)

Enables changing one or more field values of a specified check parameter.

Name

</th><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

checkDefParamId

</td><td>

String

</td><td>

Sys_id of the check parameter listed in the Check Parameter Definitions [sn_agent_check_param_def] table.

</td></tr><tr><td>

updateJson

</td><td>

Object

</td><td>

Map of check parameter fields to be updated to their new values. Refer to the data dictionary for a comprehensive list of Check Secure Parameter Definition fields and types. { "active": Boolean, "default_value": "String", "mandatory": Boolean, "name": "String" }

</td></tr><tr><td>

updateJson.active

</td><td>

Boolean

</td><td>

Flag that indicates whether the check parameter is active.

Valid values:

true: The check parameter is active.
false: The check parameter is inactive.

</td></tr><tr><td>

updateJson.default_value

</td><td>

String

</td><td>

Specifies the default value for this check parameter.

</td></tr><tr><td>

updateJson.mandatory

</td><td>

Boolean

</td><td>

Flag that indicates whether the check parameter is required.

Valid values:

true: The check parameter is required.
false: The check parameter is optional.

</td></tr><tr><td>

updateJson.name

</td><td>

String

</td><td>

Name of the check parameter.

The following example shows how to activate a check parameter.

var checkParmSysId = "cd922ce6dba530106f4810284b961966";
var updateJson = {"active": "true"};
sn_agent.AccCheckDefsAPI.updateCheckSecureParam(checkParmSysId, updateJson);

AccCheckDefsAPI - updateCheckSecureParam(String checkDefSecureParamId, Object updateJson)

Enables changing one or more field values of a specified check secure parameter.

Name

</th><th>

Type

</th><th>

Description

</th></tr></thead><tbody><tr><td>

checkDefSecureParamId

</td><td>

String

</td><td>

Sys_id of the secure parameter listed in the Check Secure Parameter Definitions [sn_agent_check_secure_param_def] table.

</td></tr><tr><td>

updateJson

</td><td>

Object

</td><td>

Map of check secure parameter fields to be updated to their new values. Refer to the data dictionary for a comprehensive list of Check Secure Parameter Definition fields and types. { "active": Boolean, "name": "String", "order": Number }

</td></tr><tr><td>

updateJson.active

</td><td>

Boolean

</td><td>

Flag that indicates whether the secure parameter is active.

Valid values:

true: The secure parameter is active.
false: The secure parameter is inactive.

</td></tr><tr><td>

updateJson.name

</td><td>

String

</td><td>

Name of the secure parameter.

</td></tr><tr><td>

updateJson.order

</td><td>

Number

</td><td>

Order in which the parameter is sent to the check command/script.

The following example shows how to activate a check secure parameter.

var checkSecParmSysId = "<sys_id>";
var updateJson = {"active": "true"};
sn_agent.AccCheckDefsAPI.updateCheckSecureParam(checkSecParmSysId, updateJson);

Keep exploring.

Find another answer, or bring this documentation into your own tools.

Search the library →Read via the REST API ↗