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 | 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 |
| Properties | Description |
|---|---|
| check | Details of the specified check definition. |
| 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. 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. 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 |
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 | 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 |
| Properties | Description |
|---|---|
| check definitions | List of check definition and details provided as JSON objects. |
| 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. 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. 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 |
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.
| Name | Type | Description |
|---|---|---|
| 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. |
| 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. |
| Type | Description |
|---|---|
| None | Error message if unsuccessful. |
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.
| Name | Type | Description |
|---|---|---|
| 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. |
| 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. |
| Type | Description |
|---|---|
| None | Error message if unsuccessful. |
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 | Type | Description |
|---|---|---|
| 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. |
| 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. |
| Type | Description |
|---|---|
| None | Error message if unsuccessful. |
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);