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.

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

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>