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

This API requires the Configuration Management Database (CMDB) application (com.snc.cmdb).

To use these methods in a scoped application, see CMDBQBScopedScriptableAPI - Scoped.

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

CMDBQueryBuilderAPI - 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.

Table 1. Parameters
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.
Table 2. Returns
TypeDescription
Object Details about the created report and any errors.
{
  "error": "String",
  "message": "String",
  "status": "String"
}
<Object>.error 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

Data type: String
<Object>.message 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

Data type: String
<Object>.status Status code. Returned when the update is successful.

Value: success

Data type: String

Example

This example shows how to create a report by passing a saved query name.

SNC.CMDBQueryBuilderAPI.createReport('', 'CMDBQueryTest1');

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"
}

Example

This example shows an error when the provided query name is invalid.

SNC.CMDBQueryBuilderAPI.createReport('', 'Test');

Output:

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

CMDBQueryBuilderAPI - deleteQuery(String savedQueryId, String savedQueryName)

Deletes a Configuration Management Database (CMDB) Query Builder query.

Table 3. Parameters
Name Type Description
savedQueryId String Sys_id of the query to delete.

This parameter is not required if a query name is provided.

Table: Saved Queries [qb_saved_query]
savedQueryName String 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.
Table 4. Returns
TypeDescription
Object 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

Example

This example shows how to delete a saved query by passing the query name.

SNC.CMDBQueryBuilderAPI.deleteQuery('', 'CMDBQueryTest1');

Output:

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

CMDBQueryBuilderAPI - 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.

Table 5. Parameters
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
Table 6. Returns
TypeDescription
Object Details about the query execution and any errors.
{
  "error": "String",
  "message": "String",
  "query_id": "String",
  "status": "String",
  "table_name": "String"
}
<Object>.error 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
<Object>.message 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
<Object>.query_id Sys_id of the query execution.

Data type: String

Table: Query Status [qb_query_status]
<Object>.status 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
<Object>.table_name Name of the table that contains the query execution details.

Data type: String

Example

This example shows how to execute a saved query and set the query execution timeout value to 10 minutes.

SNC.CMDBQueryBuilderAPI.getSavedQueryExecutionDetails('Test', true, 600);

Output:

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

CMDBQueryBuilderAPI - saveQuery(String savedQueryName, String queryJson)

Saves a Configuration Management Database (CMDB) Query Builder query and returns the sys_id of the saved query.

Table 7. Parameters
Name Type Description
savedQueryName String Name to save the query under.

Table: Saved in the Name field of the Saved Queries [qb_saved_query] table.
queryJson String JSON that defines the query.

Table: Saved in the Query field of the Saved Queries [qb_saved_query] table.
Table 8. Returns
TypeDescription
Object 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

Example

This example shows how to add a query to the Saved Queries [qb_saved_query] table.

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}}";
SNC.CMDBQueryBuilderAPI.saveQuery('CMDBQueryTest1', queryJson);

Output:

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

Example

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

var queryJson = "Test";
SNC.CMDBQueryBuilderAPI.saveQuery('Test', queryJson);

Output:

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

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

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

Table 9. Parameters
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.
Table 10. Returns
TypeDescription
Object Details about the updated query and any errors.
{
  "error": "String",
  "message": "String",
  "status": "String"
}
<Object>.error 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
<Object>.message 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
<Object>.status Status code. Returned when the update is successful.

Value: success

Data type: String

Example

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}}";
gs.log(SNC.CMDBQueryBuilderAPI.updateQuery('', 'CMDBQueryTest1', queryJson));

Output:

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

Example

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}}";
SNC.CMDBQueryBuilderAPI.updateQuery('', '', queryJson);

Output:

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