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

AccCheckDefsAPI - getCheck(String checkDefId, Boolean withParams)

Gets a specified check definition with details.

Table 1. Parameters
Name Type Description
checkDefId String Sys_id of the check definition listed in the Check Definitions [sn_agent_check_def] table.
withParams Boolean 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
Table 2. Returns
PropertiesDescription
check 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
}
check.background 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
check.check_group Group specified for this check definition.

Data type: String
check.check_type 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
check.command Command that the Agent Client Collector executes.

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

Data type: String
check.name Name of the check.

Data type: String
check.params 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
check.params.active 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
check.params.default_value Specifies the default value for this check parameter.

Data type: String
check.params.mandatory 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
check.params.name Name of the check parameter.

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

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

Data type: Array
check.proxy_valid 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
check.secure_params 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
check.secure_params.active 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
check.secure_params.name Name of the secure parameter.

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

Data type: Number
check.secure_params.sys_id Sys_id of the secure parameter listed in the Check Secure Parameter Definitions [sn_agent_check_secure_param_def] table.

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

Data type: String
check.timeout Timeout in seconds.

Data type: Number

Example

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.

Table 3. Parameters
Name Type Description
encodedQuery String An encoded query string to filter the check definition result list. Use null for an unfiltered list of check definitions in the system.
limit Number Limits the number of returned records. Set to null to use the default value.

Default: 20,000
withParams Boolean 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
Table 4. Returns
PropertiesDescription
check definitions 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
background 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
check_group Group specified for this check definition.

Data type: String
check_type 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
command Command that the Agent Client Collector executes.

Data type: String
name Name of the check.

Data type: String
params 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
params.active 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
params.default_value Specifies the default value for this check parameter.

Data type: String
params.mandatory 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
params.name Name of the check parameter.

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

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

Data type: Array
proxy_valid 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
secure_params 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
secure_params.active 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
secure_params.name Name of the secure parameter.

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

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

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

Data type: String
timeout Timeout in seconds.

Data type: Number

Example

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.

See also Checks and policies.

Table 5. Parameters
NameTypeDescription
checkDefId String Sys_id of the check definition listed in the Check Definitions [sn_agent_check_def] table.
updateJson Object Map of check definition fields to be updated to their new values. Refer to the data dictionary for a comprehensive list of Check Definition fields and types.
{
 "background": Boolean,
 "check_group": "String",
 "check_type": "String",
 "command": "String",
 "name": "String",
 "plugins": [Array],
 "proxy_valid": Boolean,
 "timeout": Number
}
updateJson.active Number Indicates whether this check definition is active.
Valid values:
  • 0: This check definition is inactive.
  • 1: This check definition is active.
updateJson.background Boolean 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.
updateJson.check_group String Group specified for this check definition.
updateJson.check_type String 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.
updateJson.command String Command that the Agent Client Collector executes.
updateJson.name String Name of the check.
updateJson.plugins Array List of Agent Client Collector plugins associated with this check.
updateJson.proxy_valid Boolean

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.
updateJson.timeout Number Timeout in seconds.
Table 6. Returns
Type Description
None Error message if unsuccessful.

Example

The following example shows how to deactivate a check definition.

var checkJson = sn_agent.AccCheckDefsAPI.getCheck(activeCheckDefs[0].sys_id, true);
if (!gs.nil(checkJson.error))
	gs.error(checkJson.error);

var updateJson = {active: "0"}; // deactivate the check definition
sn_agent.AccCheckDefsAPI.updateCheck(checkJson.check.sys_id, updateJson);

AccCheckDefsAPI - updateCheckParam(String checkDefParamId, Object updateJson)

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

Table 7. Parameters
NameTypeDescription
checkDefParamId String Sys_id of the check parameter listed in the Check Parameter Definitions [sn_agent_check_param_def] table.
updateJson Object 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"
}
updateJson.active Boolean

Flag that indicates whether the check parameter is active.

Valid values:
  • true: The check parameter is active.
  • false: The check parameter is inactive.
updateJson.default_value String Specifies the default value for this check parameter.
updateJson.mandatory Boolean

Flag that indicates whether the check parameter is required.

Valid values:
  • true: The check parameter is required.
  • false: The check parameter is optional.
updateJson.name String Name of the check parameter.
Table 8. Returns
Type Description
None Error message if unsuccessful.

Example

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.

Table 9. Parameters
NameTypeDescription
checkDefSecureParamId String Sys_id of the secure parameter listed in the Check Secure Parameter Definitions [sn_agent_check_secure_param_def] table.
updateJson Object 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
}
updateJson.active Boolean

Flag that indicates whether the secure parameter is active.

Valid values:
  • true: The secure parameter is active.
  • false: The secure parameter is inactive.
updateJson.name String Name of the secure parameter.
updateJson.order Number Order in which the parameter is sent to the check command/script.
Table 10. Returns
Type Description
None Error message if unsuccessful.

Example

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);