AgentNowHandler - Scoped
concept brazil Updated Sep 10, 2026 3 min read AgentNowHandlerAPIScoped.md
The AgentNowHandler script include provides methods that enable running check definitions on demand, checking the status of on demand executions and test check executions and for stopping background checks that were executed on demand.
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.
Parent Topic:Server API reference
AgentNowHandler - AgentNowHandler()
Creates an AgentNowHandler instance.
| Name | Type | Description |
|---|---|---|
| None |
The following example shows how to initialize AgentNowHandler.
JavaScript
var handler = new sn_agent.AgentNowHandler();AgentNowHandler - getRequestStatus(String requestId)
Gets status of the request with the given ID.
| Name | Type | Description |
|---|---|---|
| requestId | String | A check request ID generated by calling the runCheckForCis() method. |
|
Properties |
Description |
|---|---|
|
Object |
Status of the request and any applicable error message. |
|
status |
Request status.Possible values:
Data type: String |
|
err_msg |
Error message if any.Possible values:
Data type: String |
JavaScript
var handler = new sn_agent.AgentNowHandler();var check = {checkDefId: "158279505372b30034b8ddeeff7b1270"};var computerGr = new GlideRecord("cmdb_ci_computer");computerGr.query();var requestId = handler.runCheckForCis(computerGr, check, 0, 60);
var reqStatusJson = handler.getRequestStatus(requestId);gs.info(JSON.stringify(reqStatusJson));AgentNowHandler - getTestResultStatus(String testResultId)
Gets the test check status of the given test result.
| Name | Type | Description |
|---|---|---|
| testResultId | String | A test result ID generated by creating a test check request. |
|
Properties |
Description |
|---|---|
|
status |
Status of the test results.Possible values:
Data type: String |
|
output |
Output describing the status.Data type: String |
JavaScript
var testCheckStatusJson = handler.getTestResultStatus("testResultId");gs.info(JSON.stringify(testCheckStatusJson));AgentNowHandler - runCheckForCis(Object cis, Object check, Number priority, Number timeout)
Runs a check against the given configuration item.
|
Name |
Type |
Description |
|---|---|---|
|
cis |
GlideRecord of any CMDB table (any application, host, or agent) that the check is working against. | |
|
check |
Object |
Check ID and optional check parameters. ``` "check": { "checkDefId": "String", "params": {Object} } Text |
|
priority |
Number |
Priority of the request to be set on the ECC queue. Possible values:
|
|
timeout |
Number |
Value of the timeout for the request in seconds. |
The following example shows how to run a background check and get its request ID.
JavaScript
var handler = new sn_agent.AgentNowHandler();var check = {checkDefId: "028fcd5067c80010b7b72dbd2685ef4f"};var computerGr = new GlideRecord("cmdb_ci_computer");computerGr.query();var requestId = handler.runCheckForCis(computerGr, check, 0, 60);
gs.info(requestId);Output:
Text
b9cf14aedb5e30106f4810284b961990AgentNowHandler - stopBackgroundCheck(String requestId)
Stops a background check.
To start a background check, use the runCheckForCis() method.
| Name | Type | Description |
|---|---|---|
| requestId | String | The ID of a background check request generated by calling the runCheckForCis() method. |
| Type | Description |
|---|---|
| None |
The following example shows how stop executing a background check.
JavaScript
handler.stopBackgroundCheck(backRequestId);301 lines · 6.8 KB
---
title: AgentNowHandler - Scoped
description: The AgentNowHandler script include provides methods that enable running check definitions on demand, checking the status of on demand executions and test check executions and for stopping background checks that were executed on demand.Creates an AgentNowHandler instance.Gets status of the request with the given ID.Gets the test check status of the given test result.Runs a check against the given configuration item.Stops a background check.
locale: en-US
canonical_url: https://www.servicenow.com/docs/r/api-reference/server-api-reference/AgentNowHandlerAPIScoped.html
release: brazil
product: Server API Reference
classification: server-api-reference
topic_type: concept
last_updated: "2026-09-10"
reading_time_minutes: 3
breadcrumb: [Server API reference, API reference, API implementation and reference]
---
# AgentNowHandler- Scoped
The AgentNowHandler script include provides methods that enable running check definitions on demand, checking the status of on demand executions and test check executions and for stopping background checks that were executed on demand.
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://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/it-operations-management/acc-landing-page.md).
For the REST API solution, refer to [Agent Client Collector API](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/rest-apis/agnt_clnt_cll-api.md).
**Parent Topic:**[Server API reference](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/api-server.md)
## AgentNowHandler - AgentNowHandler\(\)
Creates an AgentNowHandler instance.
|Name|Type|Description|
|----|----|-----------|
|None| | |
The following example shows how to initialize AgentNowHandler.
```
var handler = new sn_agent.AgentNowHandler();
```
## AgentNowHandler - getRequestStatus\(String requestId\)
Gets status of the request with the given ID.
|Name|Type|Description|
|----|----|-----------|
|requestId|String|A check request ID generated by calling the runCheckForCis\(\) method.|
<table id="table_al2_2g2_z4b" class="returns"><thead><tr><th>
Properties
</th><th>
Description
</th></tr></thead><tbody><tr><td>
Object
</td><td>
Status of the request and any applicable error message.
</td></tr><tr><td>
status
</td><td>
Request status.Possible values:
- done – Check is successful.
- failure – Check has failed. See error message for details.
- mid\_flow – Request output is being handled by the MID server.
- processing – Check is in progress.
- timeout – Check processing exceeded time limit set in the runCheckForCis\(\) method.
Data type: String
</td></tr><tr><td>
err\_msg
</td><td>
Error message if any.Possible values:
- No agents found for relevant CIs.
- No background check request with given ID.
- No request with given ID.
- No test result with given ID.
- Request timeout.
Data type: String
</td></tr></tbody>
</table>The following example shows how to get the status of a request.
```
var handler = new sn_agent.AgentNowHandler();
var check = {checkDefId: "158279505372b30034b8ddeeff7b1270"};
var computerGr = new GlideRecord("cmdb_ci_computer");
computerGr.query();
var requestId = handler.runCheckForCis(computerGr, check, 0, 60);
var reqStatusJson = handler.getRequestStatus(requestId);
gs.info(JSON.stringify(reqStatusJson));
```
## AgentNowHandler - getTestResultStatus\(String testResultId\)
Gets the test check status of the given test result.
|Name|Type|Description|
|----|----|-----------|
|testResultId|String|A test result ID generated by creating a test check request.|
<table id="table_al2_2g2_z4b" class="returns"><thead><tr><th>
Properties
</th><th>
Description
</th></tr></thead><tbody><tr><td>
status
</td><td>
Status of the test results.Possible values:
- 0: Pending
- 1: In progress
- 2: Complete
- 3: No test result with given ID
Data type: String
</td></tr><tr><td>
output
</td><td>
Output describing the status.Data type: String
</td></tr></tbody>
</table>The following example shows how get result status of a completed test check request.
```
var testCheckStatusJson = handler.getTestResultStatus("testResultId");
gs.info(JSON.stringify(testCheckStatusJson));
```
## AgentNowHandler - runCheckForCis\(Object cis, Object check, Number priority, Number timeout\)
Runs a check against the given configuration item.
<table id="table_zk2_2g2_z4b" class="parameters"><thead><tr><th>
Name
</th><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
cis
</td><td>
[GlideRecord](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/brazil/markdown/api-reference/server-api-reference/c_GlideRecordScopedAPI.md)
</td><td>
GlideRecord of any CMDB table \(any application, host, or agent\) that the check is working against.
</td></tr><tr><td>
check
</td><td>
Object
</td><td>
Check ID and optional check parameters. ```
"check": {
"checkDefId": "String",
"params": {Object}
}
```
</td></tr><tr><td>
check.checkDefId
</td><td>
String
</td><td>
Sys\_id of a check definition in the Check Definitions \[sn\_agent\_check\_def\] table.
</td></tr><tr><td>
check.params
</td><td>
Object
</td><td>
Optional. Map of parameter names and values. These settings can be used to override the parameter records of the check definition and its specified values. ```
"params": {
"<parameter name>": "String"
}
```
</td></tr><tr><td>
priority
</td><td>
Number
</td><td>
Priority of the request to be set on the ECC queue. Possible values:
- 0: interactive
- 1: expedited
- 2: standard
</td></tr><tr><td>
timeout
</td><td>
Number
</td><td>
Value of the timeout for the request in seconds.
</td></tr></tbody>
</table>|Type|Description|
|----|-----------|
|String|Sys\_id of the generated background check request.|
The following example shows how to run a background check and get its request ID.
```
var handler = new sn_agent.AgentNowHandler();
var check = {checkDefId: "028fcd5067c80010b7b72dbd2685ef4f"};
var computerGr = new GlideRecord("cmdb_ci_computer");
computerGr.query();
var requestId = handler.runCheckForCis(computerGr, check, 0, 60);
gs.info(requestId);
```
Output:
```
b9cf14aedb5e30106f4810284b961990
```
## AgentNowHandler - stopBackgroundCheck\(String requestId\)
Stops a background check.
To start a background check, use the runCheckForCis\(\) method.
|Name|Type|Description|
|----|----|-----------|
|requestId|String|The ID of a background check request generated by calling the runCheckForCis\(\) method.|
|Type|Description|
|----|-----------|
|None| |
The following example shows how stop executing a background check.
```
handler.stopBackgroundCheck(backRequestId);
```
| title | AgentNowHandler - Scoped |
| description | The AgentNowHandler script include provides methods that enable running check definitions on demand, checking the status of on demand executions and test check executions and for stopping background checks that were executed on demand.Creates an AgentNowHandler instance.Gets status of the request with the given ID.Gets the test check status of the given test result.Runs a check against the given configuration item.Stops a background check. |
| locale | en-US |
| canonical_url | https://www.servicenow.com/docs/r/api-reference/server-api-reference/AgentNowHandlerAPIScoped.html |
| release | brazil |
| product | Server API Reference |
| classification | server-api-reference |
| topic_type | concept |
| last_updated | 2026-09-10 |
| reading_time_minutes | 3 |
| breadcrumb | Server API referenceAPI referenceAPI implementation and reference |