{"revision":"c10276e953456835cdbb1f3a60d58ae1980be353","document":{"id":704,"path":"api-reference/server-api-reference/AccAgentsAPIAPIScoped.md","title":"AccAgentsAPI - Scoped","bundle":null,"doc_type":null,"release":"australia","body":"\n# AccAgentsAPI- Scoped\n\nThe AccAgentsAPI script include enables you to perform management actions on available agents.\n\nThis 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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/it-operations-management/acc-landing-page.md).\n\nFor the REST API solution, refer to [Agent Client Collector API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/agnt_clnt_cll-api.md).\n\nThis script include provides methods that enable the following:\n\n- Getting extensive information of one or more agents.\n- Submitting a request to grab an agent log and retrieving information about the request progress.\n- Starting or stopping data collection.\n- Restarting an agent.\n- Running discovery on an agent.\n\n**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/api-server.md)\n\n## AccAgentsAPI - AccAgentsAPI\\(\\)\n\nCreates an AccAgentsAPI instance.\n\n|Name|Type|Description|\n|----|----|-----------|\n|None| | |\n\nThe following example shows how to initialize AccAgentsAPI.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\n```\n\n## AccAgentsAPI - checkGrabLogRequestProgress\\(String requestId\\)\n\nChecks the status of a grab log request.\n\nRun the [submitGrabLogRequest\\(\\)](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/AccAgentsAPIAPIScoped.md) method to get a request ID.\n\n|Name|Type|Description|\n|----|----|-----------|\n|requestId|String|Sys\\_id of a request in the Agent Client Collector Requests \\[sn\\_agent\\_request\\] table.|\n\n\n
\n\nProperties\n\n\n\nDescription\n\n
\n\n<Object>\n\n\n\nJSON object containing the grab log request status.```\n{\n \"status\": Number,\n \"output\": \"String\"\n}\n```\n\n
\n\nstatus\n\n\n\nNumber indicating status of the grab log request.Possible values:\n\n- 0: Grab log request is complete.\n- 1: Grab log request in progress.\n- 2: Grab log request timed out.\n- 3: Grab log request has an error.\n- 4: Grab log request was not found.\n\n
\n\noutput\n\n\n\nInformation describing the status.\n\n
The following example shows how to use a request ID to get the status of a grab log request.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\nvar logRequestStatus = agentsApi.checkGrabLogRequestProgress(\"\");\n\ngs.info(JSON.stringify(logRequestStatus, null, 2));\n```\n\nOutput:\n\n```\n{\n \"status\": 2,\n \"output\": \"Grab Log Request Timed Out\"\n}\n```\n\n## AccAgentsAPI - getAgent\\(String agentID\\)\n\nGets the information of a specified agent.\n\nTo get a list of agent IDs:\n\n- Run the getAgentsList\\(\\) method.\n- Check the Agent ID column of the Agent Client Collectors \\[sn\\_agent\\_cmdb\\_ci\\_agent\\] table.\n- Run the [Agent Client Collector GET list](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/agnt_clnt_cll-api.md) REST API.\n\n|Name|Type|Description|\n|----|----|-----------|\n|agentID|String|Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors \\[sn\\_agent\\_cmdb\\_ci\\_agent\\] table.|\n\n\n
\n\nProperties\n\n\n\nDescription\n\n
\n\n<Object>\n\n\n\nObject containing extended agent information.```\n{\n \"error\": String,\n \"agent\": Object\n}\n```\n\n
\n\nerror\n\n\n\nError message. Null if there is no error.Data type: String\n\n
\n\nagent\n\n\n\n```\n\"agent\": {\n \"agent_id\": \"String\",\n \"data_collection\": Number,\n \"ip_address\": \"String\",\n \"is_duplicate\": Boolean,\n \"is_restart_enabled\": Boolean,\n \"name\": \"String\",\n \"number_of_running_checks\": Number,\n \"status\": Number,\n \"up_since\": \"String\",\n \"version\": \"String\"\n }\n```\n\n
\n\nagent.agent\\_id\n\n\n\nID of the agent as submitted.Data type: String\n\n
\n\nagent.data\\_collection\n\n\n\nData 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:\n\n- 0: On – Checks run as scheduled.\n- 1: Off \\(manual\\) – Checks have been disabled manually.\n- 2: Off \\(auto\\) – Checks have been disabled automatically due to high CPU consumption by the\n\n Data type: Number\n\n
\n\nagent.ip\\_address\n\n\n\nAgent IP address.Data type: String\n\n
\n\nagent.is\\_duplicate\n\n\n\nFlag that indicates whether this agent is a duplicate of another. There should be only a single agent on a given host.\n\n Possible values:\n\n- true: The agent has the same host as an Alive/Up agent with a different agent ID. Turn off or uninstall the duplicate\n- false: This agent has no duplicates in the Alive/Up state.\n\n Data type: Boolean\n\n
\n\nagent.is\\_restart\\_enabled\n\n\n\nFlag 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.\n\n Possible values:\n\n- true: Restart is enabled for this agent.\n- false: Restart is disabled for this agent.\n\n Data type: Boolean\n\n
\n\nagent.name\n\n\n\nName of the agent.Data type: String\n\n
\n\nagent.number\\_of\\_running\\_checks\n\n\n\nThe 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\n\n
\n\nagent.status\n\n\n\nStatus of the agent.Possible values:\n\n- 0: Alive/Up – The agent is active.\n- 1: Warning – The agent has not received a keep-alive message in the past few minutes.\n- 2: Down – The agent has not received a keep-alive message in a long time.\n- 3: Restarting – The agent is restarting.\n\n Data type: Number\n\n
\n\nagent.up\\_since\n\n\n\nUTC time since the agent's status became alive/up. The value is in [GlideDateTime](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideDateTimeScoped.md) format.Data type: String\n\n
\n\nagent.version\n\n\n\nVersion of Agent Client Collector the agent is running.Data type: String\n\n
The following example shows how to display an agent's status.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\nvar agentInfo = agentsAPI.getAgent(\"\");\n\nif (!gs.nil(agentInfo.error))\n\tgs.error(agentInfo.error);\nelse\n\tgs.info(\"agent status: \" + agentInfo.agent.status);\n\n```\n\nOutput:\n\n```\nagent status: 2\n```\n\nThe following example shows how to get all agent details.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\nvar agentInfo = agentsAPI.getAgent(\"\");\n\ngs.info(JSON.stringify(agentInfo, null, 2));\n```\n\nOutput:\n\n```\n{\n \"error\": null,\n \"agent\": {\n \"name\": \"win2016-dc-64bit\",\n \"status\": 0,\n \"agent_id\": \"\",\n \"ip_address\": \"10.222.333.42\",\n \"number_of_running_checks\": 1,\n \"data_collection\": 0,\n \"is_restart_enabled\": true,\n \"is_duplicate\": false,\n \"up_since\": \"2021-03-24 11:04:38\",\n \"version\": \"2.4.0\"\n }\n}\n```\n\n## AccAgentsAPI – getAgentsList\\(String encodedQuery, Number limit\\)\n\nGets a list of agents with related information.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nencodedQuery\n\n\n\nString\n\n\n\nEncoded query string in the standard platform format.\n\n
\n\nlimit\n\n\n\nNumber\n\n\n\nOptional. Restricts results to a maximum number of agents. Use null or undefined for both if they are not required.Default/Max: 20,000\n\n
\n
\n\nProperty\n\n\n\nDescription\n\n
\n\n<Array>\n\n\n\nArray of JSON objects containing extended agent information.```\n[\n {\n \"agent_id\": \"String\",\n \"data_collection\": Number,\n \"ip_address\": \"String\",\n \"is_duplicate\": Boolean,\n \"is_restart_enabled\": Boolean,\n \"name\": \"String\",\n \"number_of_running_checks\": Number,\n \"status\": Number,\n \"up_since\": \"String\",\n \"version\": \"String\"\n }\n]\n```\n\n
\n\nagent\\_id\n\n\n\nID of the agent as submitted.Data type: String\n\n
\n\ndata\\_collection\n\n\n\nData 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:\n\n- 0: On – Checks run as scheduled.\n- 1: Off \\(manual\\) – Checks have been disabled manually.\n- 2: Off \\(auto\\) – Checks have been disabled automatically due to high CPU consumption by the\n\n Data type: Number\n\n
\n\nip\\_address\n\n\n\nAgent IP address.Data type: String\n\n
\n\nis\\_duplicate\n\n\n\nFlag that indicates whether this agent is a duplicate of another. There should be only a single agent on a given host.\n\n Possible values:\n\n- true: The agent has the same host as an Alive/Up agent with a different agent ID. Turn off or uninstall the duplicate\n- false: This agent has no duplicates in the Alive/Up state.\n\n Data type: Boolean\n\n
\n\nis\\_restart\\_enabled\n\n\n\nFlag 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.\n\n Possible values:\n\n- true: Restart is enabled for this agent.\n- false: Restart is disabled for this agent.\n\n Data type: Boolean\n\n
\n\nname\n\n\n\nName of the agent.Data type: String\n\n
\n\nnumber\\_of\\_running\\_checks\n\n\n\nThe 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\n\n
\n\nstatus\n\n\n\nStatus of the agent.Possible values:\n\n- 0: Alive/Up – The agent is active.\n- 1: Warning – The agent has not received a keep-alive message in the past few minutes.\n- 2: Down – The agent has not received a keep-alive message in a long time.\n- 3: Restarting – The agent is restarting.\n\n Data type: Number\n\n
\n\nup\\_since\n\n\n\nUTC time since the agent's status became alive/up. The value is in [GlideDateTime](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/server-api-reference/c_GlideDateTimeScoped.md) format.Data type: String\n\n
\n\nversion\n\n\n\nVersion of Agent Client Collector the agent is running.Data type: String\n\n
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.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\nvar agentList = agentsApi.getAgentsList(\"agent_extended_info.status!=2\", 2);\n\ngs.info(JSON.stringify(agentList, null, 2));\n```\n\nOutput:\n\n```\n[\n {\n \"name\": \"007-175\",\n \"status\": 0,\n \"agent_id\": \"007-175\",\n \"ip_address\": \"11.222.63.66\",\n \"number_of_running_checks\": 0,\n \"data_collection\": 0,\n \"is_restart_enabled\": false,\n \"is_duplicate\": false,\n \"up_since\": \"2021-03-24 14:36:45\",\n \"version\": \"2.4.0\"\n },\n {\n \"name\": \"win2016-dc-64bit\",\n \"status\": 0,\n \"agent_id\": \"007-64\",\n \"ip_address\": \"10.222.333.42\",\n \"number_of_running_checks\": 1,\n \"data_collection\": 0,\n \"is_restart_enabled\": true,\n \"is_duplicate\": false,\n \"up_since\": \"2021-03-24 11:04:38\",\n \"version\": \"2.4.0\"\n }\n]\n```\n\nThe following example shows how to list every agent in the system. This example uses no query and no maximum number of results.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\nvar agentList = agentsApi.getAgentsList(null, 0);\n\ngs.info(JSON.stringify(agentList, null, 2));\n```\n\nThe following example shows how to iterate over the results provided and displays each agent ID.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\n\nvar agentsList = agentsApi.getAgentsList(null, 0);\nfor (var i = 0; i < agentsList.length; i++)\n gs.info(\"agent with id: \" + agentsList[i].agent_id);\n```\n\nOutput:\n\n```\nsn_agent: agent with id: 000a00e0aa1aa3a4\nsn_agent: agent with id: 000a00e1aa1aa3a4\nsn_agent: agent with id: 000a00e2aa1aa3a4\n```\n\n## AccAgentsAPI - restartAgent\\(String agentID\\)\n\nRestarts a specified agent with alive/up status.\n\nIf Agent Client Collector performance issues occur, you can restart the agent. Manual restart is supported in the following environments:\n\n- Linux-based agents using `systemd`\n- Windows agents\n\nTo get a list of agent IDs:\n\n- Run the getAgentsList\\(\\) method.\n- Check the Agent ID column of the Agent Client Collectors \\[sn\\_agent\\_cmdb\\_ci\\_agent\\] table.\n- Run the [Agent Client Collector GET list](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/agnt_clnt_cll-api.md) REST API.\n\n|Name|Type|Description|\n|----|----|-----------|\n|agentID|String|Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors \\[sn\\_agent\\_cmdb\\_ci\\_agent\\] table.|\n\n|Type|Description|\n|----|-----------|\n|String|Error message if applicable, null otherwise.|\n\nThe following example shows how to restart an agent.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\n\nvar err = agentsApi.restartAgent(\"\");\nif (!gs.nil(err))\n\tgs.error(err);\n```\n\n## AccAgentsAPI - runDiscovery\\(String agentID\\)\n\nRuns a discovery check to locate CIs related to an agent. The specified agent must be in alive/up status.\n\nTo get a list of agent IDs:\n\n- Run the getAgentsList\\(\\) method.\n- Check the Agent ID column of the Agent Client Collectors \\[sn\\_agent\\_cmdb\\_ci\\_agent\\] table.\n- Run the [Agent Client Collector GET list](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/agnt_clnt_cll-api.md) REST API.\n\n|Name|Type|Description|\n|----|----|-----------|\n|agentID|String|Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors \\[sn\\_agent\\_cmdb\\_ci\\_agent\\] table.|\n\n|Type|Description|\n|----|-----------|\n|String|Error message if applicable, null otherwise. For example, `Agent With ID: Is Not Up: no thrown error`.|\n\nThe following example shows how to run discovery on an agent with alive/up status.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\n\nvar err = agentsApi.runDiscovery(\"\");\n\nif (!gs.nil(err))\n\tgs.error(err);\n```\n\n## AccAgentsAPI - setDataCollectionStatus\\(String agentID, Boolean status\\)\n\nSet the given data collection status \\(true/false if enabled or not\\) for a specified agent.\n\nTo get a list of agent IDs:\n\n- Run the getAgentsList\\(\\) method.\n- Check the Agent ID column of the Agent Client Collectors \\[sn\\_agent\\_cmdb\\_ci\\_agent\\] table.\n- Run the [Agent Client Collector GET list](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/australia/api-reference/rest-apis/agnt_clnt_cll-api.md) REST API.\n\n\n
\n\nName\n\n\n\nType\n\n\n\nDescription\n\n
\n\nagentID\n\n\n\nString\n\n\n\nUnique ID of an agent listed in the Agent ID column of the Agent Client Collectors \\[sn\\_agent\\_cmdb\\_ci\\_agent\\] table.\n\n
\n\nstatus\n\n\n\nBoolean\n\n\n\nFlag that indicates whether data collection is enabled for the agent.\n\n Valid values:\n\n- true: Enables data collection for this agent.\n- false: Disables data collection for this agent.\n\n Default: true\n\n
|Type|Description|\n|----|-----------|\n|String|Error message if applicable, null otherwise. For example, `Agent With ID: Is Not Up: no thrown error`.|\n\nThe following example shows how to turn on agent data collection.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\nvar err = agentsApi.setDataCollectionStatus(\"\", true);\nif (!gs.nil(err))\n gs.error(err);\n```\n\nThe following example shows how to turn off agent data collection.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\nvar err = agentsApi.setDataCollectionStatus(\"\", false);\nif (!gs.nil(err))\n gs.error(err);\n```\n\n## AccAgentsAPI - submitGrabLogRequest\\(String agentId\\)\n\nRequests the log of a specified agent with alive/up status.\n\n**Note:** To retrieve the log and check its progress, pass the request ID returned to the checkGrabLogRequestProgress\\(\\) method.\n\n|Name|Type|Description|\n|----|----|-----------|\n|agentID|String|Unique ID of an agent listed in the Agent ID column of the Agent Client Collectors \\[sn\\_agent\\_cmdb\\_ci\\_agent\\] table.|\n\n\n
\n\nProperties\n\n\n\nDescription\n\n
\n\n<Object>\n\n\n\nJSON object containing the request ID and any error information.```\n{\n \"error\": \"String\",\n \"request_id\": \"String\"\n}\n```\n\n
\n\nerror\n\n\n\nError message. Null if there is no error.Data type: String\n\n
\n\nrequest\\_id\n\n\n\nSys\\_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\\}/.\n\n Data type: String\n\n
The following example shows how to get a log request ID.\n\n```\nvar agentsApi = new sn_agent.AccAgentsAPI();\nvar submittedRequest = agentsApi.submitGrabLogRequest(\"\");\n\nif (!gs.nil(submittedRequest.error))\n gs.error(submittedRequest.error);\nelse\n gs.info(\"Request ID: \" + submittedRequest.request_id);\n```\n\nOutput:\n\n```\nRequest ID: \n```\n\n"}}