AccAgentsAPI- Scoped

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.

Parent Topic:Server API reference

AccAgentsAPI - AccAgentsAPI()

Creates an AccAgentsAPI instance.

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.

{
  "status": Number,
  "output": "String"
}

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.

{
  "error": String,
  "agent": Object
}

"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"
 }

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

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.

[
 {
   "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"
 }
]

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"
  }
]

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));

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.

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.

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.

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);

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.

{
  "error": "String",
  "request_id": "String"
}

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>