CMDBQBScopedScriptableAPI - Scoped

concept australia Updated Sep 10, 2026 8 min read CMDBQBScopedAPI.md
Raw file servicenow.com

Provides methods to execute Configuration Management Database (CMDB) Query Builder operations in server-side scripts.

This API is the scoped equivalent of CMDBQueryBuilderAPI - Global.

This API requires the Configuration Management for Scoped Apps plugin (com.snc.cmdb.scoped) and is provided within the sn_cmdb namespace.

For more information about CMDB Query Builder, see CMDB Query Builder.

Parent Topic:Server API reference

CMDBQBScopedScriptableAPI - createReport(String savedQueryId, String savedQueryName)

Creates a report that shows the results of a Configuration Management Database (CMDB) Query Builder query and returns the URL of the report.

Name

Type

Description

savedQueryId

String

Sys_id of the query to use for the report.This parameter is not required if a query name is provided.

Table: Saved Queries [qb_saved_query]

savedQueryName

String

Name of the query to use for the report.This parameter is not required if a query sys_id is provided.

Table: Saved in the Name field of the Saved Queries [qb_saved_query] table.

Type

Description

Object

Details about the created report and any errors.``` { "error": "String", "message": "String", "status": "String" }

Text
</td></tr><tr><td>
&lt;Object&gt;.error
</td><td>
Error code. Returned when the report creation fails or invalid input parameters are provided. Possible errors:
-   `USER_NOT_AUTHORIZED_EXCEPTION`-   `INVALID_PARAM`-   `QUERY_SYS_ID_INVALID`-   `REPORT_INELIGIBLE`
Data type: String
</td></tr><tr><td>
&lt;Object&gt;.message
</td><td>
Message containing details about the success or failure of the report creation.Possible messages:
-   `<report-url>`-   `User is unauthorized to create a CMDBQueryBuilder query report`-   `Invalid Parameters. Please provide either a valid sysId or a valid name of a saved query`-   `Invalid queryId. Please provide a valid saved query ID`-   `Query must have a schedule with at least one run to create a report.`
See also [Schedule a CMDB query](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/create-cmdb-query-schedule.md).
Data type: String
</td></tr><tr><td>
&lt;Object&gt;.status
</td><td>
Status code. Returned when the update is successful.Value: `success`
Data type: String
</td></tr></tbody></table>This example shows how to create a report by passing a saved query name.

var queryReport = sn_cmdb.CMDBQBScopedScriptableAPI.createReport('','CMDBQueryTest1');

gs.info(JSON.stringify(queryReport, null, 2));

Text
Output:

{ "message":"/sys_report_template.do?sysparm_report_source_id=6d299cf81bbd4210bccf42a3b24bcb7a&sysparm_type=list&sysparm_title=CMDBQueryTest1&sysparm_source_type=source&sysparm_from_list=true&sysparm_chart_size=large&sysparm_manual_labor=true", "status":"success" }

Text
This example shows an error when the query sys\_id and name are both missing from the method call.

var queryReport = sn_cmdb.CMDBQBScopedScriptableAPI.createReport('', '');

gs.info(JSON.stringify(queryReport, null, 2));

Text
Output:

{ "error":"INVALID_PARAM", "message":"Invalid Parameters. Please provide either a valid sysId or a valid name of a saved query" }

Text
## CMDBQBScopedScriptableAPI - deleteQuery\(String savedQueryId, String savedQueryName\)
Deletes a Configuration Management Database \(CMDB\) Query Builder query.
<table id="id_hxw_tn4_pbc" class="parameters"><thead><tr><th>
Name
</th><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
savedQueryId
</td><td>
String
</td><td>
Sys\_id of the query to delete.This parameter can be provided as an empty string if a query name is provided.
Table: Saved Queries \[qb\_saved\_query\]
</td></tr><tr><td>
savedQueryName
</td><td>
String
</td><td>
Name of the query to delete.This parameter is not required if a query sys\_id is provided.
Table: Saved in the *Name* field of the Saved Queries \[qb\_saved\_query\] table.
</td></tr></tbody></table><table id="id_aww_5n4_pbc" class="returns"><thead><tr><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
Object
</td><td>
Details about the deleted query and any errors.```{  "error": "String",  "message": "String",  "status": "String"}

<Object>.error

Error code. Returned when the delete operation fails or invalid input parameters are provided. Possible errors:

  • USER_NOT_AUTHORIZED_EXCEPTION
  • INVALID_PARAM
  • QUERY_DELETE_FAILED

Data type: String

<Object>.message

Message containing details about the success or failure of the delete operation.Possible messages:

  • Successfully deleted the saved query
  • User is unauthorized to delete a CMDBQueryBuilder query
  • Invalid Parameters. Please provide either a valid sysId or a valid name of a saved query
  • Failed to delete the given saved query

Data type: String

<Object>.status

Status code. Returned when the update is successful.Value: success

Data type: String
This example shows how to delete a saved query by passing the query name.
JavaScript
var delQuery = sn_cmdb.CMDBQBScopedScriptableAPI.deleteQuery('', 'CMDBQueryTest1');
gs.info(JSON.stringify(delQuery, null, 2));

Output:

JSON
{   "message":"Successfully deleted the saved query",   "status":"success"}

This example shows an error when the query sys_id and name are both missing from the method call.

JavaScript
var delQuery = sn_cmdb.CMDBQBScopedScriptableAPI.deleteQuery('', '');
gs.info(JSON.stringify(delQuery, null, 2));

Output:

JSON
{   "error":"INVALID_PARAM",   "message":"Invalid Parameters. Please provide either a valid sysId or a valid name of a saved query"}

CMDBQBScopedScriptableAPI - getSavedQueryExecutionDetails(String savedQueryName, Boolean executeQuery, Number timeout)

Returns the execution details for a Configuration Management Database (CMDB) Query Builder query.

Optionally, you can execute the query in order to return current execution details.

If a timeout or memory issue occurs while executing the query, you can fine tune the query batch size to help alleviate these problems. For more information, see Batch size for Query Builder saved queries.

Name

Type

Description

savedQueryName

String

Name of the query to retrieve execution details for. Table: Name field in the Saved Queries [qb_saved_query] table.

executeQuery

Boolean

Optional. Flag that indicates whether to execute the specified query.Valid values:

  • true: Execute the specified query and return its execution details.
  • false: Don't execute the specified query. Return the most recent execution details for the query.

Default: False

timeout

Number

Optional. Integer value that overrides the default query execution timeout limit of five minutes.Unit: Seconds

Default: Five minutes

Type

Description

Object

Details about the query execution and any errors.``` { "error": "String", "execution_batch_size": Number, "message": "String", "query_id": "String", "status": "String", "table_name": "String" }

Text
</td></tr><tr><td>
&lt;Object&gt;.error
</td><td>
Error code. Returned when the query execution fails or the specified query is not found.Possible errors:
-   `QUERY_EXECUTION_NOT_FOUND`-   `QUERY_NOT_FOUND`-   `QUERY_EXECUTION_FAILED`-   `USER_NOT_AUTHORIZED_EXCEPTION`
Data type: String
</td></tr><tr><td>
&lt;Object&gt;.execution\_batch\_size
</td><td>
Batch size of 100 allocated for the query run. This value only returns if the **executeQuery** parameter is true. See also [Batch size for CMDB Query Builder queries](https://raw.githubusercontent.com/ServiceNow/ServiceNowDocs/australia/markdown/servicenow-platform/batch-size-query.md).Data type: Number
</td></tr><tr><td>
&lt;Object&gt;.message
</td><td>
Message containing details about the error code. Returned when the query execution fails or the specified query is not found.Possible messages:
-   `Query execution details not found. Please execute the query.`-   `Given saved query not found. Please make sure you are passing the name of a saved query.`-   `Query execution failed. Please use a valid query.`-   `User is unauthorized to execute a CMDBQueryBuilder query.`
Data type: String
</td></tr><tr><td>
&lt;Object&gt;.query\_id
</td><td>
Sys\_id of the query execution.Data type: String
Table: Query Status \[qb\_query\_status\]
</td></tr><tr><td>
&lt;Object&gt;.status
</td><td>
Status of the query execution.-   COMPLETE: Execution is complete.-   FAILED: Error occurred while executing query.-   TIME\_OUT: Query execution timed out.-   MAX\_LIMIT: Maximum number of return results reached.
Data type: String
</td></tr><tr><td>
&lt;Object&gt;.table\_name
</td><td>
Name of the table that contains the query execution details.Data type: String
</td></tr></tbody></table>This example shows how to execute a saved query and set the query execution timeout value to 10 minutes.

var savedQuery = sn_cmdb.CMDBQBScopedScriptableAPI.getSavedQueryExecutionDetails('CMDBQueryTest1', true, 600);

gs.info(JSON.stringify(savedQuery, null, 2));

Text
Output:

{ "execution_batch_size": 100, "query_id":"024fd53a7773330033b5270bba106141", "table_name":"u_cmdb_qb_result_598918aacb4dbf3f1a8dcf03fce6a5d57151a4e2", "status":COMPLETE }

Text
## CMDBQBScopedScriptableAPI - saveQuery\(String savedQueryName, String queryJson\)
Saves a Configuration Management Database \(CMDB\) Query Builder query and returns the sys\_id of the saved query.
<table id="id_nfl_dym_pbc" class="parameters"><thead><tr><th>
Name
</th><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr id="save-query-name"><td>
savedQueryName
</td><td>
String
</td><td>
Name to save the query under. Table: Saved in the **Name** field of the Saved Queries \[qb\_saved\_query\] table.
</td></tr><tr id="save-query-json"><td>
queryJson
</td><td>
String
</td><td>
JSON that defines the query.Table: Saved in the **Query** field of the Saved Queries \[qb\_saved\_query\] table.
</td></tr></tbody></table><table id="id_acg_5zm_pbc" class="returns"><thead><tr><th>
Type
</th><th>
Description
</th></tr></thead><tbody><tr><td>
Object
</td><td>
Object containing details about the saved query and any errors.```{   "error": "String",   "message": "String",   "status": "String"}

<Object>.error

Error code. Returned when the save operation fails or invalid input parameters are provided. Possible errors:

  • USER_NOT_AUTHORIZED_EXCEPTION
  • QUERY_NAME_INVALID
  • QUERY_INVALID
  • QUERY_EXISTS_ALREADY
  • QUERY_SAVE_FAILED

Data type: String

<Object>.message

Message containing details about the success or failure of the save operation. Possible messages:

  • Successfully saved the query with sysId <sy_id>
  • User is unauthorized to save a CMDBQueryBuilder query
  • Query name is empty. Please provide a name
  • QueryJson is invalid. Please provide a valid queryJson
  • Query name is already used, please use a different name
  • Unexpected exception while saving the query

Data type: String

<Object>.status

Status code. Returned when the save operation is successful.Value: success

Data type: String
This example shows how to add a query to the Saved Queries \[qb\_saved\_query\] table.
JavaScript
var queryJson = "{\"type\":\"cmdb\",\"nodes\":[{\"label\":\"Server\",\"unique_id\":\"d93f96981b310210bccf42a3b24bcb41\",\"nodeType\":\"class\",\"image\":\"images/app.ngbsm/server.svg\",\"properties\":\"\",\"allowed_connections\":[],\"filters\":{\"platform\":\"cmdb_ci_server\",\"custom\":\"\"},\"ci_type\":\"cmdb_ci_server\",\"ci_type_label\":\"Server\",\"sys_id\":\"d93f96981b310210bccf42a3b24bcb41\",\"x\":72,\"y\":337,\"returnValues\":[],\"filters_attrib\":\"\",\"applied_filters\":\"\",\"isStartNode\":true,\"nodeId\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"name\":\"Server 1\",\"type\":\"class\",\"refFilterApplied\":false,\"focused\":false,\"id\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"className\":\"cmdb_ci_server\"},{\"label\":\"Database\",\"unique_id\":\"b640269c1b310210bccf42a3b24bcb36\",\"nodeType\":\"class\",\"image\":\"images/app.ngbsm/database.svg\",\"properties\":\"\",\"allowed_connections\":[],\"filters\":{\"platform\":\"cmdb_ci_database\",\"custom\":\"\"},\"ci_type\":\"cmdb_ci_database\",\"ci_type_label\":\"Database\",\"sys_id\":\"b640269c1b310210bccf42a3b24bcb36\",\"x\":510,\"y\":340,\"returnValues\":[],\"filters_attrib\":\"\",\"applied_filters\":\"\",\"isStartNode\":false,\"nodeId\":\"b640269c1b310210bccf42a3b24bcb36_4_23_2024_5_50_57\",\"name\":\"Database 1\",\"type\":\"class\",\"refFilterApplied\":false,\"focused\":false,\"id\":\"b640269c1b310210bccf42a3b24bcb36_4_23_2024_5_50_57\",\"className\":\"cmdb_ci_database\"}],\"edges\":[{\"id\":\"Server 1_Database 1\",\"from\":\"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54\",\"to\":\"b640269c1b310210bccf42a3b24bcb36_4_23_2024_5_50_57\",\"isDotted\":false,\"type\":\"relation\",\"isReverse\":false,\"direction\":\"outbound\",\"hiddenLevel\":0,\"relations\":[\"607ad1b2c0a8010e01941856b365af90\",\"1a9cb166f1571100a92eb60da2bce5c5\"]}],\"usedNames\":{\"cmdb_ci_server\":1,\"cmdb_ci_database\":1}}";
var newQuery = sn_cmdb.CMDBQBScopedScriptableAPI.saveQuery('CMDBQueryTest1', queryJson);
gs.info(JSON.stringify(newQuery, null, 2));

Output:

JSON
{   "message":"Successfully saved the query with sysId d93f96981b310210bccf42a3b24bcb41",   "status":"success"}

This example shows an error when an invalid JSON query is provided.

JavaScript
var queryJson = "Test";var newQuery = sn_cmdb.CMDBQBScopedScriptableAPI.saveQuery('Test', queryJson);
gs.info(JSON.stringify(newQuery, null, 2));

Output:

JSON
{   "error":"QUERY_INVALID",   "message":"QueryJson is invalid. Please provide a valid queryJson"}

CMDBQBScopedScriptableAPI - updateQuery(String savedQueryId, String savedQueryName, String queryJson)

Updates the JSON for a Configuration Management Database (CMDB) Query Builder query.

Name

Type

Description

savedQueryId

String

Sys_id of the query to update.This parameter is not required if a query name is provided.

Table: Saved Queries [qb_saved_query]

savedQueryName

String

Name of the query to update.This parameter is not required if a query sys_id is provided.

Table: Saved in the Name field in the Saved Queries [qb_saved_query] table.

queryJson

String

JSON to update the query with.Table: Saved in the Query field in the Saved Queries [qb_saved_query] table.

Type

Description

Object

Details about the updated query and any errors.``` { "error": "String", "message": "String", "status": "String" }

Text
</td></tr><tr><td>
&lt;Object&gt;.error
</td><td>
Error code. Returned when the update fails or invalid input parameters are provided. Possible errors:
-   `USER_NOT_AUTHORIZED_EXCEPTION`-   `INVALID_PARAM`-   `QUERY_INVALID`-   `QUERY_UPDATE_FAILED`-   `UNAUTHORIZED_REPORT_SOURCE_USER`
Data type: String
</td></tr><tr><td>
&lt;Object&gt;.message
</td><td>
Message containing details about the success or failure of the update. Possible messages:
-   `Successfully updated the saved query`-   `User is unauthorized to update a CMDBQueryBuilder query`-   `Invalid Parameters. Please provide either a valid sysId or a valid name of a saved query`-   `QueryJson is invalid. Please provide a valid queryJson`-   `Failed to update the given saved query`-   `User is unauthorized to update report source of a saved query`
Data type: String
</td></tr><tr><td>
&lt;Object&gt;.status
</td><td>
Status code. Returned when the update is successful.Value: `success`
Data type: String
</td></tr></tbody></table>This example shows how to update a saved query by passing the query name.

var queryJson = "{"type":"cmdb","nodes":[{"label":"Server","unique_id":"d93f96981b310210bccf42a3b24bcb41","nodeType":"class","image":"images/app.ngbsm/server.svg","properties":"","allowed_connections":[],"filters":{"platform":"cmdb_ci_server","custom":""},"ci_type":"cmdb_ci_server","ci_type_label":"Server","sys_id":"d93f96981b310210bccf42a3b24bcb41","x":72,"y":336,"returnValues":[],"filters_attrib":"","applied_filters":"","isStartNode":true,"nodeId":"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54","name":"Server 1","type":"class","refFilterApplied":false,"focused":false,"id":"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54","className":"cmdb_ci_server"},{"label":"Web Server","unique_id":"984f5a981b310210bccf42a3b24bcb03","nodeType":"class","image":"images/app.ngbsm/web_server.svg","properties":"","allowed_connections":[],"filters":{"platform":"cmdb_ci_web_server","custom":""},"ci_type":"cmdb_ci_web_server","ci_type_label":"Web Server","sys_id":"984f5a981b310210bccf42a3b24bcb03","x":446,"y":330,"returnValues":[],"filters_attrib":"","applied_filters":"","isStartNode":false,"nodeId":"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19","name":"Web Server 1","type":"class","refFilterApplied":false,"focused":false,"id":"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19","className":"cmdb_ci_web_server"}],"edges":[{"id":"Server 1_Web Server 1","from":"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54","to":"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19","isDotted":false,"type":"relation","isReverse":false,"direction":"outbound","hiddenLevel":0,"relations":["607ad1b2c0a8010e01941856b365af90"]}],"usedNames":{"cmdb_ci_server":1,"cmdb_ci_database":1,"cmdb_ci_web_server":1}}";

var queryUpdate = sn_cmdb.CMDBQBScopedScriptableAPI.updateQuery('', 'CMDBQueryTest1', queryJson);

gs.info(JSON.stringify(queryUpdate, null, 2));

Text
Output:

{ "message":"Successfully updated the saved query", "status":"success" }

Text
This example shows an error when the query sys\_id and name are both missing from the method call.

var queryJson = "{"type":"cmdb","nodes":[{"label":"Server","unique_id":"d93f96981b310210bccf42a3b24bcb41","nodeType":"class","image":"images/app.ngbsm/server.svg","properties":"","allowed_connections":[],"filters":{"platform":"cmdb_ci_server","custom":""},"ci_type":"cmdb_ci_server","ci_type_label":"Server","sys_id":"d93f96981b310210bccf42a3b24bcb41","x":72,"y":336,"returnValues":[],"filters_attrib":"","applied_filters":"","isStartNode":true,"nodeId":"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54","name":"Server 1","type":"class","refFilterApplied":false,"focused":false,"id":"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54","className":"cmdb_ci_server"},{"label":"Web Server","unique_id":"984f5a981b310210bccf42a3b24bcb03","nodeType":"class","image":"images/app.ngbsm/web_server.svg","properties":"","allowed_connections":[],"filters":{"platform":"cmdb_ci_web_server","custom":""},"ci_type":"cmdb_ci_web_server","ci_type_label":"Web Server","sys_id":"984f5a981b310210bccf42a3b24bcb03","x":446,"y":330,"returnValues":[],"filters_attrib":"","applied_filters":"","isStartNode":false,"nodeId":"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19","name":"Web Server 1","type":"class","refFilterApplied":false,"focused":false,"id":"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19","className":"cmdb_ci_web_server"}],"edges":[{"id":"Server 1_Web Server 1","from":"d93f96981b310210bccf42a3b24bcb41_4_23_2024_5_50_54","to":"984f5a981b310210bccf42a3b24bcb03_4_23_2024_6_32_19","isDotted":false,"type":"relation","isReverse":false,"direction":"outbound","hiddenLevel":0,"relations":["607ad1b2c0a8010e01941856b365af90"]}],"usedNames":{"cmdb_ci_server":1,"cmdb_ci_database":1,"cmdb_ci_web_server":1}}";

var queryUpdate = sn_cmdb.CMDBQBScopedScriptableAPI.updateQuery('', '', queryJson);

gs.info(JSON.stringify(queryUpdate, null, 2));

Text
Output:

{ "error":"INVALID_PARAM", "message":"Invalid Parameters. Please provide either a valid sysId or a valid name of a saved query" }

Text
Search documentation
Search document titles and file paths on the australia branch