{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":705,"path":"api-reference/server-api-reference/AccCheckDefsAPIAPIScoped.md","title":"AccCheckDefsAPI - Scoped","bundle":null,"doc_type":null,"release":"australia","body":"\n# AccCheckDefsAPI- Scoped\n\nThe AccCheckDefsAPI script include enables managing check definitions and associated parameters.\n\nThis 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](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-operations-management/acc-landing-page.md).\n\nThis script include does not have a constructor for creating an instance. Call each method using the AccCheckDefsAPI static class in the following format:\n\n`sn_agent.AccCheckDefsAPI.`\n\nFor the REST API solution, refer to [Agent Client Collector API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/agnt_clnt_cll-api.md).\n\nThis script include provides methods that enable the following:\n\n- Get a specified check definition\n- Get a list of check definitions\n- Update checks and check parameters\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## AccCheckDefsAPI - getCheck\\(String checkDefId, Boolean withParams\\)\n\nGets a specified check definition with details.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\ncheckDefId\n\n\n\nString\n\n\n\nSys\\_id of the check definition listed in the Check Definitions \\[sn\\_agent\\_check\\_def\\] table.\n\n
\n\nwithParams\n\n\n\nBoolean\n\n\n\nFlag 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:\n\n- true: Return check parameter details.\n- false: Do not return check parameter details.\n\n Default: False\n\n
\n
\n\nProperties\n\n\n\nDescription\n\n
\n\ncheck\n\n\n\nDetails of the specified check definition.```\n\"check \": {\n \"background\": Boolean,\n \"check_group\": \"String\",\n \"check_type\": \"String\",\n \"command\": \"String\",\n \"error\": \"String\",\n \"name\": \"String\",\n \"params\": [Array],\n \"plugins\": [Array],\n \"proxy_valid\": Boolean,\n \"secure_params\": [Array],\n \"sys_id\": \"String\",\n \"timeout\": Number\n}\n```\n\n
\n\ncheck.background\n\n\n\nFlag 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:\n\n- true: This check definition is a background check.\n- false: This check definition is not a background check.\n\n Data type: Boolean\n\n
\n\ncheck.check\\_group\n\n\n\nGroup specified for this check definition. Data type: String\n\n
\n\ncheck.check\\_type\n\n\n\nType of check. Possible values:\n\n- Events – Check results are transformed into an Event Management event.\n- Metrics – Values from the check result are transformed to metrics.\n\n Data type: String\n\n
\n\ncheck.command\n\n\n\nCommand that the Agent Client Collector executes. Data type: String\n\n
\n\ncheck.error\n\n\n\nMessage if there is an error. Null otherwise.Data type: String\n\n
\n\ncheck.name\n\n\n\nName of the check. Data type: String\n\n
\n\ncheck.params\n\n\n\nList of parameter definitions associated with the check definition. These results are only included if the **withParams** parameter is set to true.```\n\"params\": [\n {\n \"active\": Boolean,\n \"default_value\": \"String\",\n \"mandatory\": Boolean,\n \"name\": \"String\",\n \"sys_id\": \"String\"\n }\n]\n```\n\n Data type: Array\n\n
\n\ncheck.params.active\n\n\n\nFlag that indicates whether the check parameter is active. Valid values:\n\n- true: The check parameter is active.\n- false: The check parameter is inactive.\n\n Data type: Boolean\n\n
\n\ncheck.params.default\\_value\n\n\n\nSpecifies the default value for this check parameter. Data type: String\n\n
\n\ncheck.params.mandatory\n\n\n\nFlag that indicates whether the check parameter is required. Valid values:\n\n- true: The check parameter is required.\n- false: The check parameter is optional.\n\n Data type: Boolean\n\n
\n\ncheck.params.name\n\n\n\nName of the check parameter. Data type: String\n\n
\n\ncheck.params.sys\\_id\n\n\n\nSys\\_id of the check parameter listed in the Check Secure Parameter Definitions \\[sn\\_agent\\_check\\_param\\_def\\] table. Data type: String\n\n
\n\ncheck.plugins\n\n\n\nList of [Agent Client Collector plugins](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-operations-management/acc-assets.md) associated with this check. Data type: Array\n\n
\n\ncheck.proxy\\_valid\n\n\n\nFlag that indicates whether the check definition policy is set to work as a proxy. Valid values:\n\n- true: This check definition policy is set to work as a proxy.\n- false: This check definition policy is not set to work as a proxy.\n\n Data type: Boolean\n\n
\n\ncheck.secure\\_params\n\n\n\nList of assigned to this check. These results are only included if the **withParams** parameter is set to true.```\n\"secure_params\": [\n {\n \"active\": Boolean,\n \"name\": \"String\",\n \"order\": Number,\n \"sys_id\": \"String\"\n }\n]\n```\n\n Data type: Array\n\n
\n\ncheck.secure\\_params.active\n\n\n\nFlag that indicates whether the secure parameter is active. Valid values:\n\n- true: The secure parameter is active.\n- false: The secure parameter is inactive.\n\n Data type: Boolean\n\n
\n\ncheck.secure\\_params.name\n\n\n\nName of the secure parameter. Data type: String\n\n
\n\ncheck.secure\\_params.order\n\n\n\nOrder in which the parameter is sent to the check command/script. Data type: Number\n\n
\n\ncheck.secure\\_params.sys\\_id\n\n\n\nSys\\_id of the secure parameter listed in the Check Secure Parameter Definitions \\[sn\\_agent\\_check\\_secure\\_param\\_def\\] table. Data type: String\n\n
\n\ncheck.sys\\_id\n\n\n\nSys\\_id of the check definition listed in the Check Definitions \\[sn\\_agent\\_check\\_def\\] table. Data type: String\n\n
\n\ncheck.timeout\n\n\n\nTimeout in seconds. Data type: Number\n\n
The following example shows how to get information for a specified check definition.\n\n```\nvar checkDefId = \"94436b237f705300f128134f8dfa91a4\";\nvar withParams = true;\n\nvar checkDef = sn_agent.AccCheckDefsAPI.getCheck(checkDefId, withParams);\n\ngs.info(JSON.stringify(checkDef, null, 2));\n```\n\nOutput:\n\n```\n{\n \"check\": {\n \"name\": \"app.apache.metrics-apache\",\n \"command\": \"metrics-apache-graphite.rb -p {{.labels.params_port}} --path {{.labels.params_path}} -h {{.labels.params_host}}\",\n \"plugins\": [\n \"monitoring-plugin-common\"\n ],\n \"timeout\": 60,\n \"proxy_valid\": true,\n \"background\": false,\n \"check_type\": \"Metrics\",\n \"check_group\": \"Apache\",\n \"sys_id\": \"94436b237f705300f128134f8dfa91a4\",\n \"params\": [\n {\n \"name\": \"port\",\n \"active\": true,\n \"mandatory\": true,\n \"default_value\": \"80\",\n \"sys_id\": \"58436b237f705300f128134f8dfa91a8\"\n },\n {\n \"name\": \"path\",\n \"active\": true,\n \"mandatory\": true,\n \"default_value\": \"/server-status?auto\",\n \"sys_id\": \"98436b237f705300f128134f8dfa91aa\"\n },\n {\n \"name\": \"scheme\",\n \"active\": false,\n \"mandatory\": false,\n \"default_value\": null,\n \"sys_id\": \"a4e57a96db3bbb4035305c55dc9619f6\"\n },\n {\n \"name\": \"host\",\n \"active\": true,\n \"mandatory\": true,\n \"default_value\": \"127.0.0.1\",\n \"sys_id\": \"d4436b237f705300f128134f8dfa91a6\"\n },\n {\n \"name\": \"ssl_secure_connection\",\n \"active\": false,\n \"mandatory\": false,\n \"default_value\": null,\n \"sys_id\": \"e3b272c4530100106ffeddeeff7b1275\"\n }\n ],\n \"secure_params\": [\n {\n \"name\": \"cred_user_name\",\n \"active\": true,\n \"order\": 1,\n \"sys_id\": \"2494cd6e53170010f42cddeeff7b1273\"\n },\n {\n \"name\": \"cred_password\",\n \"active\": true,\n \"order\": 2,\n \"sys_id\": \"35948d6e53170010f42cddeeff7b127f\"\n }\n ]\n },\n \"error\": null\n}\n```\n\n## AccCheckDefsAPI - getChecksList\\(String encodedQuery, Number limit, Boolean withParams\\)\n\nGets a list of check definitions with details.\n\nSee also [Checks and policies](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-operations-management/checks-policies.md).\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nencodedQuery\n\n\n\nString\n\n\n\nAn [encoded query string](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/platform-user-interface/c_EncodedQueryStrings.md) to filter the check definition result list. Use null for an unfiltered list of check definitions in the system.\n\n
\n\nlimit\n\n\n\nNumber\n\n\n\nLimits the number of returned records. Set to null to use the default value. Default: 20,000\n\n
\n\nwithParams\n\n\n\nBoolean\n\n\n\nFlag 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:\n\n- true: Return check parameter details.\n- false: Do not return check parameter details.\n\n Default: False\n\n
\n
\n\nProperties\n\n\n\nDescription\n\n
\n\ncheck definitions\n\n\n\nList of check definition and details provided as JSON objects.```\n[\n {\n \"background\": Boolean,\n \"check_group\": \"String\",\n \"check_type\": \"String\",\n \"command\": \"String\",\n \"name\": \"String\",\n \"params\": [Array],\n \"plugins\": [Array],\n \"proxy_valid\": Boolean,\n \"secure_params\": [Array],\n \"sys_id\": \"String\",\n \"timeout\": Number\n }\n]\n```\n\n Data type: Array\n\n
\n\nbackground\n\n\n\nFlag 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:\n\n- true: This check definition is a background check.\n- false: This check definition is not a background check.\n\n Data type: Boolean\n\n
\n\ncheck\\_group\n\n\n\nGroup specified for this check definition. Data type: String\n\n
\n\ncheck\\_type\n\n\n\nType of check. Possible values:\n\n- Events – Check results are transformed into an Event Management event.\n- Metrics – Values from the check result are transformed to metrics.\n\n Data type: String\n\n
\n\ncommand\n\n\n\nCommand that the Agent Client Collector executes. Data type: String\n\n
\n\nname\n\n\n\nName of the check. Data type: String\n\n
\n\nparams\n\n\n\nList of parameter definitions associated with the check definition. These results are only included if the **withParams** parameter is set to true.```\n\"params\": [\n {\n \"active\": Boolean,\n \"default_value\": \"String\",\n \"mandatory\": Boolean,\n \"name\": \"String\",\n \"sys_id\": \"String\"\n }\n]\n```\n\n Data type: Array\n\n
\n\nparams.active\n\n\n\nFlag that indicates whether the check parameter is active. Valid values:\n\n- true: The check parameter is active.\n- false: The check parameter is inactive.\n\n Data type: Boolean\n\n
\n\nparams.default\\_value\n\n\n\nSpecifies the default value for this check parameter. Data type: String\n\n
\n\nparams.mandatory\n\n\n\nFlag that indicates whether the check parameter is required. Valid values:\n\n- true: The check parameter is required.\n- false: The check parameter is optional.\n\n Data type: Boolean\n\n
\n\nparams.name\n\n\n\nName of the check parameter. Data type: String\n\n
\n\nparams.sys\\_id\n\n\n\nSys\\_id of the check parameter listed in the Check Secure Parameter Definitions \\[sn\\_agent\\_check\\_param\\_def\\] table. Data type: String\n\n
\n\nplugins\n\n\n\nList of [Agent Client Collector plugins](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-operations-management/acc-assets.md) associated with this check. Data type: Array\n\n
\n\nproxy\\_valid\n\n\n\nFlag that indicates whether the check definition policy is set to work as a proxy. Valid values:\n\n- true: This check definition policy is set to work as a proxy.\n- false: This check definition policy is not set to work as a proxy.\n\n Data type: Boolean\n\n
\n\nsecure\\_params\n\n\n\nList of assigned to this check. These results are only included if the **withParams** parameter is set to true.```\n\"secure_params\": [\n {\n \"active\": Boolean,\n \"name\": \"String\",\n \"order\": Number,\n \"sys_id\": \"String\"\n }\n]\n```\n\n Data type: Array\n\n
\n\nsecure\\_params.active\n\n\n\nFlag that indicates whether the secure parameter is active. Valid values:\n\n- true: The secure parameter is active.\n- false: The secure parameter is inactive.\n\n Data type: Boolean\n\n
\n\nsecure\\_params.name\n\n\n\nName of the secure parameter. Data type: String\n\n
\n\nsecure\\_params.order\n\n\n\nOrder in which the parameter is sent to the check command/script. Data type: Number\n\n
\n\nsecure\\_params.sys\\_id\n\n\n\nSys\\_id of the secure parameter listed in the Check Secure Parameter Definitions \\[sn\\_agent\\_check\\_secure\\_param\\_def\\] table. Data type: String\n\n
\n\nsys\\_id\n\n\n\nSys\\_id of the check definition listed in the Check Definitions \\[sn\\_agent\\_check\\_def\\] table. Data type: String\n\n
\n\ntimeout\n\n\n\nTimeout in seconds. Data type: Number\n\n
The following example shows how to retrieve a list of two check definitions with parameter values.\n\n```\nvar encQuery = \"nameSTARTSWITHchecks_\";\nvar limit = 2;\nvar withParams = true;\n\nvar checkDefs = sn_agent.AccCheckDefsAPI.getChecksList(encQuery, limit, withParams);\n\ngs.info(JSON.stringify(checkDefs, null, 2));\n```\n\nOutput:\n\n```\n[\n {\n \"name\": \"checks_api_test\",\n \"command\": \"echo hello\",\n \"plugins\": [],\n \"timeout\": 9,\n \"proxy_valid\": true,\n \"background\": false,\n \"check_type\": \"TestCheck\",\n \"check_group\": \"computer\",\n \"sys_id\": \"7f1f9026dba530106f4810284b96194f\",\n \"params\": [],\n \"secure_params\": [\n {\n \"name\": \"check_api_test_check_secure_param2\",\n \"active\": true,\n \"order\": 2,\n \"sys_id\": \"2d30a066dba530106f4810284b9619c1\"\n },\n {\n \"name\": \"check_api_test_check_secure_param1\",\n \"active\": true,\n \"order\": 100,\n \"sys_id\": \"4c20a066dba530106f4810284b9619a8\"\n }\n ]\n },\n {\n \"name\": \"checks_api_test222\",\n \"command\": \"echo hello1212121\",\n \"plugins\": [],\n \"timeout\": 60,\n \"proxy_valid\": true,\n \"background\": false,\n \"check_type\": \"TestCheck\",\n \"check_group\": \"computer\",\n \"sys_id\": \"99e12466dba530106f4810284b961976\",\n \"params\": [\n {\n \"name\": \"check_api_test_check_param_222\",\n \"active\": true,\n \"mandatory\": false,\n \"default_value\": \"test_test_test\",\n \"sys_id\": \"44026466dba530106f4810284b9619b2\"\n }\n ],\n \"secure_params\": []\n }\n]\n```\n\n## AccCheckDefsAPI - updateCheck\\(String checkDefId, Object updateJson\\)\n\nEnables changing one or more field values of a specified check definition.\n\nSee also [Checks and policies](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-operations-management/checks-policies.md).\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\ncheckDefId\n\n\n\nString\n\n\n\nSys\\_id of the check definition listed in the Check Definitions \\[sn\\_agent\\_check\\_def\\] table.\n\n
\n\nupdateJson\n\n\n\nObject\n\n\n\nMap 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.```\n{\n \"background\": Boolean,\n \"check_group\": \"String\",\n \"check_type\": \"String\",\n \"command\": \"String\",\n \"name\": \"String\",\n \"plugins\": [Array],\n \"proxy_valid\": Boolean,\n \"timeout\": Number\n}\n```\n\n
\n\nupdateJson.active\n\n\n\nNumber\n\n\n\nIndicates whether this check definition is active.Valid values:\n\n- 0: This check definition is inactive.\n- 1: This check definition is active.\n\n
\n\nupdateJson.background\n\n\n\nBoolean\n\n\n\nFlag 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:\n\n- true: This check definition is a background check.\n- false: This check definition is not a background check.\n\n
\n\nupdateJson.check\\_group\n\n\n\nString\n\n\n\nGroup specified for this check definition.\n\n
\n\nupdateJson.check\\_type\n\n\n\nString\n\n\n\nType of check.Possible values:\n\n- Events – Check results are transformed into an Event Management event.\n- Metrics – Values from the check result are transformed to metrics.\n\n
\n\nupdateJson.command\n\n\n\nString\n\n\n\nCommand that the Agent Client Collector executes.\n\n
\n\nupdateJson.name\n\n\n\nString\n\n\n\nName of the check.\n\n
\n\nupdateJson.plugins\n\n\n\nArray\n\n\n\nList of [Agent Client Collector plugins](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-operations-management/acc-assets.md) associated with this check.\n\n
\n\nupdateJson.proxy\\_valid\n\n\n\nBoolean\n\n\n\nFlag that indicates whether the check definition policy is set to work as a proxy.\n\n Valid values:\n\n- true: This check definition policy is set to work as a proxy.\n- false: This check definition policy is not set to work as a proxy.\n\n
\n\nupdateJson.timeout\n\n\n\nNumber\n\n\n\nTimeout in seconds.\n\n
|Type|Description|\n|----|-----------|\n|None|Error message if unsuccessful.|\n\nThe following example shows how to deactivate a check definition.\n\n```\nvar checkJson = sn_agent.AccCheckDefsAPI.getCheck(activeCheckDefs[0].sys_id, true);\nif (!gs.nil(checkJson.error))\n\tgs.error(checkJson.error);\n\nvar updateJson = {active: \"0\"}; // deactivate the check definition\nsn_agent.AccCheckDefsAPI.updateCheck(checkJson.check.sys_id, updateJson);\n```\n\n## AccCheckDefsAPI - updateCheckParam\\(String checkDefParamId, Object updateJson\\)\n\nEnables changing one or more field values of a specified check parameter.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\ncheckDefParamId\n\n\n\nString\n\n\n\nSys\\_id of the check parameter listed in the Check Parameter Definitions \\[sn\\_agent\\_check\\_param\\_def\\] table.\n\n
\n\nupdateJson\n\n\n\nObject\n\n\n\nMap 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.```\n{\n \"active\": Boolean,\n \"default_value\": \"String\",\n \"mandatory\": Boolean,\n \"name\": \"String\"\n}\n```\n\n
\n\nupdateJson.active\n\n\n\nBoolean\n\n\n\nFlag that indicates whether the check parameter is active.\n\n Valid values:\n\n- true: The check parameter is active.\n- false: The check parameter is inactive.\n\n
\n\nupdateJson.default\\_value\n\n\n\nString\n\n\n\nSpecifies the default value for this check parameter.\n\n
\n\nupdateJson.mandatory\n\n\n\nBoolean\n\n\n\nFlag that indicates whether the check parameter is required.\n\n Valid values:\n\n- true: The check parameter is required.\n- false: The check parameter is optional.\n\n
\n\nupdateJson.name\n\n\n\nString\n\n\n\nName of the check parameter.\n\n
|Type|Description|\n|----|-----------|\n|None|Error message if unsuccessful.|\n\nThe following example shows how to activate a check parameter.\n\n```\nvar checkParmSysId = \"cd922ce6dba530106f4810284b961966\";\nvar updateJson = {\"active\": \"true\"};\nsn_agent.AccCheckDefsAPI.updateCheckSecureParam(checkParmSysId, updateJson);\n```\n\n## AccCheckDefsAPI - updateCheckSecureParam\\(String checkDefSecureParamId, Object updateJson\\)\n\nEnables changing one or more field values of a specified check secure parameter.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\ncheckDefSecureParamId\n\n\n\nString\n\n\n\nSys\\_id of the secure parameter listed in the Check Secure Parameter Definitions \\[sn\\_agent\\_check\\_secure\\_param\\_def\\] table.\n\n
\n\nupdateJson\n\n\n\nObject\n\n\n\nMap 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.```\n{\n \"active\": Boolean,\n \"name\": \"String\",\n \"order\": Number\n}\n```\n\n
\n\nupdateJson.active\n\n\n\nBoolean\n\n\n\nFlag that indicates whether the secure parameter is active.\n\n Valid values:\n\n- true: The secure parameter is active.\n- false: The secure parameter is inactive.\n\n
\n\nupdateJson.name\n\n\n\nString\n\n\n\nName of the secure parameter.\n\n
\n\nupdateJson.order\n\n\n\nNumber\n\n\n\nOrder in which the parameter is sent to the check command/script.\n\n
|Type|Description|\n|----|-----------|\n|None|Error message if unsuccessful.|\n\nThe following example shows how to activate a check secure parameter.\n\n```\nvar checkSecParmSysId = \"\";\nvar updateJson = {\"active\": \"true\"};\nsn_agent.AccCheckDefsAPI.updateCheckSecureParam(checkSecParmSysId, updateJson);\n```\n\n"}}