CMDBQBScopedScriptableAPI - Scoped

  • Release version: Xanadu
  • Updated August 1, 2024
  • 7 minutes to read

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

    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.

    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
    Type Description
    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
    • REPORT_INELIGIBLE

    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
    • Query must have a schedule with at least one run to create a report.
    See also Schedule a CMDB query.

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

    Value: success

    Data type: String

    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));

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

    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));

    Output:

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

    CMDBQBScopedScriptableAPI - 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 can be provided as an empty string 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
    Type Description
    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

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

    gs.info(JSON.stringify(sn_cmdb.CMDBQBScopedScriptableAPI.deleteQuery('', 'CMDBQueryTest1')));

    Output:

    {
   "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.

    gs.info(JSON.stringify(sn_cmdb.CMDBQBScopedScriptableAPI.deleteQuery('', '')));

    Output:

    {
   "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.

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

    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));

    Output:

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

    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 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
    Type Description
    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

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

var newQuery = sn_cmdb.CMDBQBScopedScriptableAPI.saveQuery('CMDBQueryTest1', queryJson);

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

    Output:

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

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

    var queryJson = "Test";
var newQuery = sn_cmdb.CMDBQBScopedScriptableAPI.saveQuery('Test', queryJson);

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

    Output:

    {
   "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.

    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
    Type Description
    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

    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));

    Output:

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

    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));

    Output:

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