--- sourceDocument: Xanadu API Reference sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/xanadu/api-reference Release : - xanadu ft:locale : - en-US ft:publication_title : - Xanadu API Reference ft:clusterId : - crapiref bundleId : - crapiref workflow : - Creator --- # AccAgentsAPI - Scoped # AccAgentsAPI - Scoped {#ariaid-title1} * Release version: Xanadu * * Updated August 1, 2024 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 9 minutes to read 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](https://www.servicenow.com/docs/access?context=acc-landing-page&version=xanadu&pubname=xanadu-it-operations-management&ft:locale=en-US). For the REST API solution, refer to [Agent Client Collector API](https://servicenow-prod.fluidtopics.net/VqZ3eXHD4gCQogGcocPm9A#agnt_clnt_cll-api "The Agent Client Collector API provides endpoints to manage actions on available agents and managing policies."). 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() {#ariaid-title2} Creates an AccAgentsAPI instance. {#AccA-AccAgentsAPI__table_ohr_4qd_bpb__entry__3} | Name | Type | Description | |-|-|-| | None | | | [Table 1. Parameters] {#AccA-AccAgentsAPI__table_ohr_4qd_bpb} The following example shows how to initialize AccAgentsAPI. var agentsApi = new sn_agent.AccAgentsAPI(); ## AccAgentsAPI - checkGrabLogRequestProgress(String requestId) {#ariaid-title3} Checks the status of a grab log request. Run the [submitGrabLogRequest()](https://servicenow-prod.fluidtopics.net/QNzIaZ~J9utrU444mAJXkg#AccA-submitGrabLogRequest_S "Requests the log of a specified agent with alive/up status.") method to get a request ID. {#AccA-checkGrabLogRequestProgress_S__table_zk2_2g2_z4b__entry__3}{#AccA-checkGrabLogRequestProgress_S__accAgents-parm-desc-requestID} | Name | Type | Description | |-|-|-| | requestId | String | Sys_id of a request in the Agent Client Collector Requests \[sn_agent_request\] table. | [Table 2. Parameters] {#AccA-checkGrabLogRequestProgress_S__table_zk2_2g2_z4b} {#AccA-checkGrabLogRequestProgress_S__table_al2_2g2_z4b__entry__2} | Properties | Description | |-|-| | \ | 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. {#AccA-checkGrabLogRequestProgress_S__ul_orq_4qr_bpb} | | output | Information describing the status. | [Table 3. Returns] {#AccA-checkGrabLogRequestProgress_S__table_al2_2g2_z4b} 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(""); gs.info(JSON.stringify(logRequestStatus, null, 2)); Output: { "status": 2, "output": "Grab Log Request Timed Out" } ## AccAgentsAPI - getAgent(String agentID) {#ariaid-title4} 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](https://servicenow-prod.fluidtopics.net/VqZ3eXHD4gCQogGcocPm9A#agnt_clnt_cll-GET-list "Gets a list of agents with related information.") REST API. {#AccA-getAgent_S__ul_yqc_3kj_z4b} {#AccA-getAgent_S__table_zk2_2g2_z4b__entry__3}{#AccA-getAgent_S__accAgents-parm-desc-agentID} | 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 4. Parameters] {#AccA-getAgent_S__table_zk2_2g2_z4b} {#AccA-getAgent_S__table_al2_2g2_z4b__entry__2}{#AccA-getAgent_S__accAgents-rtrns-error} | Properties | Description | |-|-| | \ | 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 {#AccA-getAgent_S__ul_w4n_53p_bpb} 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. {#AccA-getAgent_S__ul_b34_ffl_bpb} 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. {#AccA-getAgent_S__ul_bvp_dfl_bpb} 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. {#AccA-getAgent_S__ul_adg_ffp_bpb} Data type: Number | | agent.up_since | UTC time since the agent's status became alive/up. The value is in [GlideDateTime](https://servicenow-prod.fluidtopics.net/xOhnNqU1cKMjoQSfmtxVCw#c_GlideDateTimeScoped "The scoped GlideDateTime class provides methods for performing operations on GlideDateTime objects.") format. Data type: String | | agent.version | Version of Agent Client Collector the agent is running. Data type: String | [Table 5. Returns] {#AccA-getAgent_S__table_al2_2g2_z4b} The following example shows how to display an agent's status. var agentsApi = new sn_agent.AccAgentsAPI(); var agentInfo = agentsAPI.getAgent(""); 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(""); gs.info(JSON.stringify(agentInfo, null, 2)); Output: { "error": null, "agent": { "name": "win2016-dc-64bit", "status": 0, "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) {#ariaid-title5} Gets a list of agents with related information. {#AccA-getAgentsList_S_N__table_zk2_2g2_z4b__entry__3} | Name | Type | Description | |-|-|-| | encodedQuery | String | Encoded query string in standard Glide format. See [Encoded query strings](https://www.servicenow.com/docs/access?context=c_EncodedQueryStrings&version=xanadu&pubname=xanadu-platform-user-interface&ft:locale=en-US). | | 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 6. Parameters] {#AccA-getAgentsList_S_N__table_zk2_2g2_z4b} {#AccA-getAgentsList_S_N__table_al2_2g2_z4b__entry__2}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-id-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-dataCollect-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-ip-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-dup-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-restart-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-name-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-numChecks-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-status-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-up-entry}{#AccA-getAgentsList_S_N__accAgents-parm-agent-obj-version-entry} | Property | Description | |-|-| | \ | 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 {#AccA-getAgentsList_S_N__ul_w4n_53p_bpb} 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. {#AccA-getAgentsList_S_N__ul_b34_ffl_bpb} 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. {#AccA-getAgentsList_S_N__ul_bvp_dfl_bpb} 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. {#AccA-getAgentsList_S_N__ul_adg_ffp_bpb} Data type: Number | | up_since | UTC time since the agent's status became alive/up. The value is in [GlideDateTime](https://servicenow-prod.fluidtopics.net/xOhnNqU1cKMjoQSfmtxVCw#c_GlideDateTimeScoped "The scoped GlideDateTime class provides methods for performing operations on GlideDateTime objects.") format. Data type: String | | version | Version of Agent Client Collector the agent is running. Data type: String | [Table 7. Returns] {#AccA-getAgentsList_S_N__table_al2_2g2_z4b} 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) {#ariaid-title6} 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 {#AccA-restartAgent_S__ul_zzv_z4q_dpb} 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](https://servicenow-prod.fluidtopics.net/VqZ3eXHD4gCQogGcocPm9A#agnt_clnt_cll-GET-list "Gets a list of agents with related information.") REST API. {#AccA-restartAgent_S__ul_yqc_3kj_z4b} {#AccA-restartAgent_S__table_zk2_2g2_z4b__entry__3}{#AccA-restartAgent_S__accAgents-parm-desc-agentID} | 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 8. Parameters] {#AccA-restartAgent_S__table_zk2_2g2_z4b} {#AccA-restartAgent_S__table_al2_2g2_z4b__entry__2} | Type | Description | |-|-| | String | Error message if applicable, null otherwise. | [Table 9. Returns] {#AccA-restartAgent_S__table_al2_2g2_z4b} The following example shows how to restart an agent. var agentsApi = new sn_agent.AccAgentsAPI(); var err = agentsApi.restartAgent(""); if (!gs.nil(err)) gs.error(err); ## AccAgentsAPI - runDiscovery(String agentID) {#ariaid-title7} 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](https://servicenow-prod.fluidtopics.net/VqZ3eXHD4gCQogGcocPm9A#agnt_clnt_cll-GET-list "Gets a list of agents with related information.") REST API. {#AccA-runDiscovery_S__ul_yqc_3kj_z4b} {#AccA-runDiscovery_S__table_zk2_2g2_z4b__entry__3}{#AccA-runDiscovery_S__accAgents-parm-desc-agentID} | 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 10. Parameters] {#AccA-runDiscovery_S__table_zk2_2g2_z4b} {#AccA-runDiscovery_S__table_al2_2g2_z4b__entry__2} | Type | Description | |-|-| | String | Error message if applicable, null otherwise. For example, `Agent With ID: Is Not Up: no thrown error`. | [Table 11. Returns] {#AccA-runDiscovery_S__table_al2_2g2_z4b} 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(""); if (!gs.nil(err)) gs.error(err); ## AccAgentsAPI - setDataCollectionStatus(String agentID, Boolean status) {#ariaid-title8} 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](https://servicenow-prod.fluidtopics.net/VqZ3eXHD4gCQogGcocPm9A#agnt_clnt_cll-GET-list "Gets a list of agents with related information.") REST API. {#AccA-setDataCollectionStatus_S_B__ul_yqc_3kj_z4b} {#AccA-setDataCollectionStatus_S_B__table_zk2_2g2_z4b__entry__3}{#AccA-setDataCollectionStatus_S_B__accAgents-parm-desc-agentID} | 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. {#AccA-setDataCollectionStatus_S_B__ul_iv2_jcz_bpb} Default: true | [Table 12. Parameters] {#AccA-setDataCollectionStatus_S_B__table_zk2_2g2_z4b} {#AccA-setDataCollectionStatus_S_B__table_al2_2g2_z4b__entry__2} | Type | Description | |-|-| | String | Error message if applicable, null otherwise. For example, `Agent With ID: Is Not Up: no thrown error`. | [Table 13. Returns] {#AccA-setDataCollectionStatus_S_B__table_al2_2g2_z4b} The following example shows how to turn on agent data collection. var agentsApi = new sn_agent.AccAgentsAPI(); var err = agentsApi.setDataCollectionStatus("", 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("", false); if (!gs.nil(err)) gs.error(err); ## AccAgentsAPI - submitGrabLogRequest(String agentId) {#ariaid-title9} 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. {#AccA-submitGrabLogRequest_S__table_zk2_2g2_z4b__entry__3}{#AccA-submitGrabLogRequest_S__accAgents-parm-desc-agentID} | 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 14. Parameters] {#AccA-submitGrabLogRequest_S__table_zk2_2g2_z4b} {#AccA-submitGrabLogRequest_S__table_al2_2g2_z4b__entry__2} | Properties | Description | |-|-| | \ | 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 | [Table 15. Returns] {#AccA-submitGrabLogRequest_S__table_al2_2g2_z4b} The following example shows how to get a log request ID. var agentsApi = new sn_agent.AccAgentsAPI(); var submittedRequest = agentsApi.submitGrabLogRequest(""); if (!gs.nil(submittedRequest.error)) gs.error(submittedRequest.error); else gs.info("Request ID: " + submittedRequest.request_id); Output: Request ID: