AccAgentsAPI - Scoped
-
- UpdatedJan 30, 2025
- 8 minutes to read
- Yokohama
- API reference
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.
- 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.
Name | Type | Description |
---|---|---|
None |
Example
The following example shows how to initialize AccAgentsAPI.
AccAgentsAPI - checkGrabLogRequestProgress(String requestId)
Checks the status of a grab log request.
Run the submitGrabLogRequest() method to get a request ID.
Name | Type | Description |
---|---|---|
requestId | String | Sys_id of a request in the Agent Client Collector Requests [sn_agent_request] table. |
Properties | Description |
---|---|
<Object> | JSON object containing the grab log request status. |
status | Number indicating status of the grab log request. Possible values:
|
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.
Output:
AccAgentsAPI - getAgent(String agentID)
Gets the information of a specified agent.
- 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.
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.
Output:
Example
The following example shows how to get all agent details.
Output:
AccAgentsAPI – getAgentsList(String encodedQuery, Number limit)
Gets a list of agents with related information.
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.
Output:
Example
The following example shows how to list every agent in the system. This example uses no query and no maximum number of results.
Example
The following example shows how to iterate over the results provided and displays each agent ID.
Output:
AccAgentsAPI - restartAgent(String agentID)
Restarts a specified agent with alive/up status.
- Linux-based agents using
systemd
- Windows agents
- 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.
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. |
Type | Description |
---|---|
String | Error message if applicable, null otherwise. |
Example
The following example shows how to restart an agent.
AccAgentsAPI - runDiscovery(String agentID)
Runs a discovery check to locate CIs related to an agent. The specified agent must be in alive/up status.
- 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.
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. |
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.
AccAgentsAPI - setDataCollectionStatus(String agentID, Boolean status)
Set the given data collection status (true/false if enabled or not) for a specified agent.
- 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.
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:
Default: true |
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.
Example
The following example shows how to turn off agent data collection.
AccAgentsAPI - submitGrabLogRequest(String agentId)
Requests the log of a specified agent with alive/up status.
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. |
Properties | Description |
---|---|
<Object> | JSON object containing the request ID and any error information. |
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.
Output:
On this page
- AccAgentsAPI - AccAgentsAPI()
- AccAgentsAPI - checkGrabLogRequestProgress(String requestId)
- AccAgentsAPI - getAgent(String agentID)
- AccAgentsAPI – getAgentsList(String encodedQuery, Number limit)
- AccAgentsAPI - restartAgent(String agentID)
- AccAgentsAPI - runDiscovery(String agentID)
- AccAgentsAPI - setDataCollectionStatus(String agentID, Boolean status)
- AccAgentsAPI - submitGrabLogRequest(String agentId)