AccCheckDefsAPI - Scoped

  • Rversion finale: Australia
  • Mis à jour 12 mars 2026
  • 10 minutes de lecture

    • 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.

    Tableau 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
    Tableau 2. Returns
    Properties Description
    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

    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.

    Tableau 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
    Tableau 4. Returns
    Properties Description
    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

    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.

    Tableau 5. Parameters
    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.
    {
 "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.
    Tableau 6. Returns
    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.

    Tableau 7. Parameters
    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.
    {
 "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.
    Tableau 8. Returns
    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.

    Tableau 9. Parameters
    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.
    {
 "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.
    Tableau 10. Returns
    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);