The AccAgentsAPI script include enables you to perform management actions on available agents.

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

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

This script include provides methods that enable the following:
  • Getting extensive information of one or more agents.
  • Submitting a request to grab an agent log and retrieving information about the request progress.
  • Starting or stopping data collection.
  • Restarting an agent.
  • Running discovery on an agent.

AccAgentsAPI - AccAgentsAPI()

Creates an AccAgentsAPI instance.

Table 1. Parameters
Name Type Description
None

Example

The following example shows how to initialize AccAgentsAPI.

var agentsApi = new sn_agent.AccAgentsAPI();

AccAgentsAPI - checkGrabLogRequestProgress(String requestId)

Checks the status of a grab log request.

Run the submitGrabLogRequest() method to get a request ID.

Table 2. Parameters
Name Type Description
requestId String Sys_id of a request in the Agent Client Collector Requests [sn_agent_request] table.
Table 3. Returns
Properties Description
<Object> JSON object containing the grab log request status.
{
  "status": Number,
  "output": "String"
}
status Number indicating status of the grab log request.
Possible values:
  • 0: Grab log request is complete.
  • 1: Grab log request in progress.
  • 2: Grab log request timed out.
  • 3: Grab log request has an error.
  • 4: Grab log request was not found.
output Information describing the status.

Example

The following example shows how to use a request ID to get the status of a grab log request.

var agentsApi = new sn_agent.AccAgentsAPI();
var logRequestStatus = agentsApi.checkGrabLogRequestProgress("<request_ID>");

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

Output:

{
  "status": 2,
  "output": "Grab Log Request Timed Out"
}

AccAgentsAPI - getAgent(String agentID)

Gets the information of a specified agent.

To get a list of agent IDs:
  • Run the getAgentsList() method.
  • Check the Agent ID column of the Agent Client Collectors [sn_agent_cmdb_ci_agent] table.
  • Run the Agent Client Collector GET list REST API.
Table 4. Parameters
Name Type Description
agentID String Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors [sn_agent_cmdb_ci_agent] table.
Table 5. Returns
PropertiesDescription
<Object> Object containing extended agent information.
{
  "error": String,
  "agent": Object
}
error Error message. Null if there is no error.

Data type: String
agent 
"agent": {
   "agent_id": "String",
   "data_collection": Number,
   "ip_address": "String",
   "is_duplicate": Boolean,
   "is_restart_enabled": Boolean,
   "name": "String",
   "number_of_running_checks": Number,
   "status": Number,
   "up_since": "String",
   "version": "String"
 }
agent.agent_id ID of the agent as submitted.

Data type: String
agent.data_collection Data collection indicates whether scheduled checks are to be run. These checks are a part of the policies scheduled for this agent to run.
Possible values:
  • 0: On – Checks run as scheduled.
  • 1: Off (manual) – Checks have been disabled manually.
  • 2: Off (auto) – Checks have been disabled automatically due to high CPU consumption by the

Data type: Number
agent.ip_address Agent IP address.

Data type: String
agent.is_duplicate

Flag that indicates whether this agent is a duplicate of another. There should be only a single agent on a given host.

Possible values:
  • true: The agent has the same host as an Alive/Up agent with a different agent ID. Turn off or uninstall the duplicate
  • false: This agent has no duplicates in the Alive/Up state.

Data type: Boolean
agent.is_restart_enabled

Flag that indicates whether restart is enabled. Agent restart is not configurable. It depends on the OS and the version of the OS the agent is running on.

Possible values:
  • true: Restart is enabled for this agent.
  • false: Restart is disabled for this agent.

Data type: Boolean
agent.name Name of the agent.

Data type: String
agent.number_of_running_checks The number of checks the agent is scheduled to run. These checks are a part of the policies scheduled for this agent to run.

Data type: Number
agent.status Status of the agent.
Possible values:
  • 0: Alive/Up – The agent is active.
  • 1: Warning – The agent has not received a keep-alive message in the past few minutes.
  • 2: Down – The agent has not received a keep-alive message in a long time.
  • 3: Restarting – The agent is restarting.

Data type: Number
agent.up_since UTC time since the agent's status became alive/up. The value is in GlideDateTime format.

Data type: String
agent.version Version of Agent Client Collector the agent is running.

Data type: String

Example

The following example shows how to display an agent's status.

var agentsApi = new sn_agent.AccAgentsAPI();
var agentInfo = agentsAPI.getAgent("<agent_ID>");

if (!gs.nil(agentInfo.error))
	gs.error(agentInfo.error);
else
	gs.info("agent status: " + agentInfo.agent.status);

Output:

agent status: 2

Example

The following example shows how to get all agent details.

var agentsApi = new sn_agent.AccAgentsAPI();
var agentInfo = agentsAPI.getAgent("<agent_ID>");

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

Output:

{
  "error": null,
  "agent": {
    "name": "win2016-dc-64bit",
    "status": 0,
    "agent_id": "<agent_ID>",
    "ip_address": "10.222.333.42",
    "number_of_running_checks": 1,
    "data_collection": 0,
    "is_restart_enabled": true,
    "is_duplicate": false,
    "up_since": "2021-03-24 11:04:38",
    "version": "2.4.0"
  }
}

AccAgentsAPI – getAgentsList(String encodedQuery, Number limit)

Gets a list of agents with related information.

Table 6. Parameters
Name Type Description
encodedQuery String Encoded query string in standard Glide format. See Encoded query strings.
limit Number Optional. Restricts results to a maximum number of agents. Use null or undefined for both if they are not required.

Default/Max: 20,000
Table 7. Returns
PropertyDescription
<Array> Array of JSON objects containing extended agent information.
[
 {
   "agent_id": "String",
   "data_collection": Number,
   "ip_address": "String",
   "is_duplicate": Boolean,
   "is_restart_enabled": Boolean,
   "name": "String",
   "number_of_running_checks": Number,
   "status": Number,
   "up_since": "String",
   "version": "String"
 }
]
agent_id ID of the agent as submitted.

Data type: String
data_collection Data collection indicates whether scheduled checks are to be run. These checks are a part of the policies scheduled for this agent to run.
Possible values:
  • 0: On – Checks run as scheduled.
  • 1: Off (manual) – Checks have been disabled manually.
  • 2: Off (auto) – Checks have been disabled automatically due to high CPU consumption by the

Data type: Number
ip_address Agent IP address.

Data type: String
is_duplicate

Flag that indicates whether this agent is a duplicate of another. There should be only a single agent on a given host.

Possible values:
  • true: The agent has the same host as an Alive/Up agent with a different agent ID. Turn off or uninstall the duplicate
  • false: This agent has no duplicates in the Alive/Up state.

Data type: Boolean
is_restart_enabled

Flag that indicates whether restart is enabled. Agent restart is not configurable. It depends on the OS and the version of the OS the agent is running on.

Possible values:
  • true: Restart is enabled for this agent.
  • false: Restart is disabled for this agent.

Data type: Boolean
name Name of the agent.

Data type: String
number_of_running_checks The number of checks the agent is scheduled to run. These checks are a part of the policies scheduled for this agent to run.

Data type: Number
status Status of the agent.
Possible values:
  • 0: Alive/Up – The agent is active.
  • 1: Warning – The agent has not received a keep-alive message in the past few minutes.
  • 2: Down – The agent has not received a keep-alive message in a long time.
  • 3: Restarting – The agent is restarting.

Data type: Number
up_since UTC time since the agent's status became alive/up. The value is in GlideDateTime format.

Data type: String
version Version of Agent Client Collector the agent is running.

Data type: String

Example

The following example shows how to restrict results by query and number. The query returns all agents that are not in the down state with a maximum of two results.

var agentsApi = new sn_agent.AccAgentsAPI();
var agentList = agentsApi.getAgentsList("agent_extended_info.status!=2", 2);

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

Output:

[
  {
    "name": "007-175",
    "status": 0,
    "agent_id": "007-175",
    "ip_address": "11.222.63.66",
    "number_of_running_checks": 0,
    "data_collection": 0,
    "is_restart_enabled": false,
    "is_duplicate": false,
    "up_since": "2021-03-24 14:36:45",
    "version": "2.4.0"
  },
  {
    "name": "win2016-dc-64bit",
    "status": 0,
    "agent_id": "007-64",
    "ip_address": "10.222.333.42",
    "number_of_running_checks": 1,
    "data_collection": 0,
    "is_restart_enabled": true,
    "is_duplicate": false,
    "up_since": "2021-03-24 11:04:38",
    "version": "2.4.0"
  }
]

Example

The following example shows how to list every agent in the system. This example uses no query and no maximum number of results.

var agentsApi = new sn_agent.AccAgentsAPI();
var agentList = agentsApi.getAgentsList(null, 0);

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

Example

The following example shows how to iterate over the results provided and displays each agent ID.

var agentsApi = new sn_agent.AccAgentsAPI();

var agentsList = agentsApi.getAgentsList(null, 0);
for (var i = 0; i < agentsList.length; i++)
   gs.info("agent with id: " + agentsList[i].agent_id);

Output:

sn_agent: agent with id: 000a00e0aa1aa3a4
sn_agent: agent with id: 000a00e1aa1aa3a4
sn_agent: agent with id: 000a00e2aa1aa3a4

AccAgentsAPI - restartAgent(String agentID)

Restarts a specified agent with alive/up status.

If Agent Client Collector performance issues occur, you can restart the agent. Manual restart is supported in the following environments:
  • Linux-based agents using systemd
  • Windows agents
To get a list of agent IDs:
  • Run the getAgentsList() method.
  • Check the Agent ID column of the Agent Client Collectors [sn_agent_cmdb_ci_agent] table.
  • Run the Agent Client Collector GET list REST API.
Table 8. Parameters
Name Type Description
agentID String Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors [sn_agent_cmdb_ci_agent] table.
Table 9. Returns
Type Description
String Error message if applicable, null otherwise.

Example

The following example shows how to restart an agent.

var agentsApi = new sn_agent.AccAgentsAPI();

var err = agentsApi.restartAgent("<agent_ID>");
if (!gs.nil(err))
	gs.error(err);

AccAgentsAPI - runDiscovery(String agentID)

Runs a discovery check to locate CIs related to an agent. The specified agent must be in alive/up status.

To get a list of agent IDs:
  • Run the getAgentsList() method.
  • Check the Agent ID column of the Agent Client Collectors [sn_agent_cmdb_ci_agent] table.
  • Run the Agent Client Collector GET list REST API.
Table 10. Parameters
Name Type Description
agentID String Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors [sn_agent_cmdb_ci_agent] table.
Table 11. Returns
Type Description
String Error message if applicable, null otherwise. For example, Agent With ID: <agentID> Is Not Up: no thrown error.

Example

The following example shows how to run discovery on an agent with alive/up status.

var agentsApi = new sn_agent.AccAgentsAPI();

var err = agentsApi.runDiscovery("<agent_ID>");

if (!gs.nil(err))
	gs.error(err);

AccAgentsAPI - setDataCollectionStatus(String agentID, Boolean status)

Set the given data collection status (true/false if enabled or not) for a specified agent.

To get a list of agent IDs:
  • Run the getAgentsList() method.
  • Check the Agent ID column of the Agent Client Collectors [sn_agent_cmdb_ci_agent] table.
  • Run the Agent Client Collector GET list REST API.
Table 12. Parameters
Name Type Description
agentID String Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors [sn_agent_cmdb_ci_agent] table.
status Boolean

Flag that indicates whether data collection is enabled for the agent.

Valid values:
  • true: Enables data collection for this agent.
  • false: Disables data collection for this agent.

Default: true
Table 13. Returns
Type Description
String Error message if applicable, null otherwise. For example, Agent With ID: <agentID> Is Not Up: no thrown error.

Example

The following example shows how to turn on agent data collection.

var agentsApi = new sn_agent.AccAgentsAPI();
var err = agentsApi.setDataCollectionStatus("<agentID>", true);
if (!gs.nil(err))
   gs.error(err);

Example

The following example shows how to turn off agent data collection.

var agentsApi = new sn_agent.AccAgentsAPI();
var err = agentsApi.setDataCollectionStatus("<agentID>", false);
if (!gs.nil(err))
   gs.error(err);

AccAgentsAPI - submitGrabLogRequest(String agentId)

Requests the log of a specified agent with alive/up status.

Note: To retrieve the log and check its progress, pass the request ID returned to the checkGrabLogRequestProgress() method.
Table 14. Parameters
Name Type Description
agentID String Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors [sn_agent_cmdb_ci_agent] table.
Table 15. Returns
Properties Description
<Object> JSON object containing the request ID and any error information.
{
  "error": "String",
  "request_id": "String"
}
error Error message. Null if there is no error.

Data type: String
request_id Sys_id of a request in the Agent Client Collector Requests [sn_agent_request] table.

You can use this ID to get the status of the request using GET /agents/{request_id}/.

Data type: String

Example

The following example shows how to get a log request ID.

var agentsApi = new sn_agent.AccAgentsAPI();
var submittedRequest = agentsApi.submitGrabLogRequest("<agentID>");

if (!gs.nil(submittedRequest.error))
   gs.error(submittedRequest.error);
else
   gs.info("Request ID: " + submittedRequest.request_id);

Output:

Request ID: <sys_id>