HPE Software is now Micro Focus
HPE Software is now Micro Focus
IT Service Management
cancel

UCMDB’s REST API – How to utilize the capabilities

UCMDB’s REST API – How to utilize the capabilities

Ops_Guest

REst API.PNG

 Guest post by Niklas Agethen, Professional Services

Micro Focus Configuration Management System UCMDB provides a REST API to access its resources from external tools and applications. This API is a great feature if the integration of UCMDB data into another application is desired. The related tool of this documentation, the UCMDB TQL Exporter, is an exemplary use case to show how the REST API can be used. This blog post concentrates on the main features of the REST API and how to use them. Additional Information on how to access UCMDB contents via API are provided by:

  • UCMDB TQL Exporter documentation
  • UCMDB TQL Exporter source code
  • UCMDB Developer Reference Guide from CMS Helpcenter

(These documents are provided in the attached file on the right rail of this blog.)

Prerequisites

To utilize these contents make sure that the REST API is supported by your UCMDB version and is deployed properly. Depending on the UCMDB version, the REST API might not be deployed automatically. Since CMS version 10.30 the REST API is deployed automatically when installing the UCMDB Server. If using a version between 10.10 and 10.30, the API can be deployed standalone. Consult the Developer Reference Guide from UCMDB Helpcenter for additional information on standalone deployment. Unfortunately, UCMDB versions lower than 10.10 do not support the REST API.

After deploying the REST API successfully, the API can be accessed via the URL ‘http(s)://<baseurl>/rest-api’, where the base URL is the URL of the server running the REST API (if not installed standalone, the base URL of the UCMDB server).

To access the UCMDB via REST API a user with specific access rights is needed. The user needs to have a role with the right “Access to SDK” enabled. Check the permissions of the user by visiting “Security” à “Users and Groups” in the UCMDB UI. If resources from the UCMDB, such as views, queries, etc., are accessed via API, make sure that the API user and its role(s) have the right to access them.

Authentication

To access methods from the API, a prior authentication is necessary. Therefore you need to send your username, password and client context to the authentication endpoint of the API (‘http(s)://<baseurl>/rest-api/authenticate’). Use the method of your programming language to send a post request to the authentication URL containing the username, password and client context as JSON formatted post data. By default the customer Id is ‘1’.

An exemplary post data body might look like the following:

{
                             “username” : “admin”,
                             “password” : “admin”,
                             “clientContext” : 1
              }

Do not forget to specify the content type of your post data in the request’s header as ‘application/json’:

{

‘Content-Type’ : ‘application/json’

}

As a response to a successful authentication an access token is returned in JSON format. This token must be added to any further API requests to authenticate at the API.

Further information on how to authenticate at the API can be found at the UCMDB TQL Exporter documentation (page 7) and source code (class RestClient).

Execute TQLs via API

In this case the execution of a pre-defined TQL is desired. Make sure that the TQL exists in the connected UCMDB and that the user, who authenticated at the API, has the right to execute that TQL. To execute a TQL you need to send a post request to the TQL execution endpoint of the API (‘http(s)://<baseurl>/rest-api/topology’). Use the method of your programming language to send a post request to that URL, having set the TQL name in the post body and a valid access token from authentication endpoint in the headers.

The header of the request must contain the access token of the request:

              {

‘Authorization’ : ‘Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NzQzNT
c3MDYsImN1c3RvbWVyIjoxLCJ1c2VybmFtZSI6InN5c2FkbWluIn0.cVYsuum1CqaqfZV1K5KJ8nidOOif8Wv9tZsLFFZPbSs’

}

Do not forget to set ‘Bearer’ keyword in front of your token (see example above).

The body of the TQL execution request simply contains the name of the TQL you wish to execute. Just send the TQL name as String without any brackets or apostrophes. A sample post body might look like the following:

              sample_tql_name

In case of a successful request, the response object contains all the TQL results split into CIs and relations. Use the UCMDB UI to hide CI types from the result object by opening the TQL and right-click on the specific CI type. Additionally, you can adjust the attributes of a CI type shown in the result object by accessing the ‘Element Layout’ tab of the Query Node Properties. In the screenshot below the UCMDB user interface of the Element Layout tab is shown. Move the desired attribute from the ‘Available Attributes’ pane to ‘Specific Attributes’ pane to show this attribute in the API results of the TQL. By Default only the UCMDB ID and CI type are provided.Quarry Node Preperation.png

 

A sample response from the topology endpoint of the API might look like the following, where the display label has been specified within ‘Element Layout’ tab:

              {

                             “cis”: [

                                           {

“ucmdbId”: “a599as29a0d0c333240d67ad7e0664960”,
“type”: “nt”,
“properties”: {

“display_label”: “c9w16542”
}

},

{

“ucmdbId”: "4825a55778dd533739c0373012f26cd4",
“type”: “iis”,
“properties”: {
              “display_label”: “iis_web_server”
}

}

],
“relations”: [
              {
                             “ucmdbId”: "4174635364f893d38d60fbd4806756c3",
                             “type”: “composition”,
                             “properties”: null,
                             “end1Id”: “a599as29a0d0c333240d67ad7e0664960”,
                             “end2Id”: "4825a55778dd533739c0373012f26cd4"

}

]

}

In addition to the TQL execution explained above, it is also possible to define and execute a TQL just by the API request. Instead of executing an existing TQL you can define your TQL within the post data of your request and receive the TQL results as response. Therefore another endpoint of the API has to be used. For any details of that kind of TQL execution consult the Developer Reference Guide.

Further information on how to execute a TQL via REST API can be found at the UCMDB TQL Exporter documentation (page 7) and source code (class RestClient).

Get CI data via API

If you wish to request a CI and its attributes via REST API, the CI endpoint is required. Use the method of your programming language to send a get request to the URL ‘http(s)://<baseurl>/rest-api/dataModel/ci/{id}’, where the {Id} needs to be replaced by the Id of the desired CI. Make sure to add a valid access token from authentication endpoint to the headers of the request.

A sample header of the request might look like the following:

{

‘Authorization’ : ‘Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NzQzNT
c3MDYsImN1c3RvbWVyIjoxLCJ1c2VybmFtZSI6InN5c2FkbWluIn0.cVYsuum1CqaqfZV1K5KJ8nidOOif8Wv9tZsLFFZPbSs’

}

Do not forget to set ‘Bearer’ keyword in front of your token (see example above).

If the request has been successful, the JSON response object of the API contains the desired CI and its attributes. A sample response would look like the following:

{

    "ucmdbId": "ada54c49ed057ebeb1c94dab1128c29c",

    "type": "node",

    "properties": {

        "root_candidatefordeletetime": "2016-11-16T03:25:40.780Z",

        "data_operationisnew": "false",

        "root_class": "node",

        "TenantsUses": [

            "System Default Tenant"

        ],

        "display_label": "adv-desktop-101",

        "data_operationstate": "0:Normal",

        "node_role": [

            "desktop"

        ],

        "data_allow_auto_discovery": "true",

        "root_actualdeletetime": "2016-12-06T03:25:40.780Z",

        "data_teststate": "0:Normal",

        "default_gateway_ip_address_type": "IPv4",

        "data_changecorrstate": "0:No Change",

        "last_modified_time": "2016-10-18T07:34:28.601Z",

        "create_time": "2016-10-18T07:34:28.601Z",

        "TenantOwner": "System Default Tenant",

        "data_changestate": "0:No Change",

        "global_id": "6c9b4645166551f82fb3869f297aae22",

        "data_testisnew": "false",

        "root_lastaccesstime": "2016-10-27T03:25:40.780Z",

        "root_iscandidatefordeletion": "false",

        "data_source": "ServiceManager: DS_ServiceManager_SM Configuration Items Population job",

        "data_changeisnew": "false",

        "data_testcorrstate": "0:Normal",

        "track_changes": "false",

        "host_iscomplete": "false",

        "name": "adv-desktop-101",

        "data_operationcorrstate": "0:Normal",

        "is_save_persistency": "false",

        "data_adminstate": "0:Managed",

        "root_enableageing": "false",

        "data_updated_by": "ServiceManager: DS_ServiceManager_SM Configuration Items Population job"

    }

}

Get Related CIs via API

The API provides an endpoint to return all the related CIs of a given CI specified by its Id. Therefore you simply need to send a get request to the related CIs endpoint of the API with the URL ‘http(s)://<baseurl>/rest-api/dataModel/relatedCI/{id}’, where the {id} needs to be replaced by the Id of the CI, whose relations you want to request. Use the method of your programming language to send a get request to that URL, having a valid access token from authentication endpoint specified in the headers.

The header of the request must contain the access token of the request:

              {

‘Authorization’ : ‘Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NzQzNT
c3MDYsImN1c3RvbWVyIjoxLCJ1c2VybmFtZSI6InN5c2FkbWluIn0.cVYsuum1CqaqfZV1K5KJ8nidOOif8Wv9tZsLFFZPbSs’

}

Do not forget to set ‘Bearer’ keyword in front of your token (see example above).

In case of a successful request, the response object contains all the related CIs with its attributes and its relations. The relations are separated from the CIs and contain the Id of the two CIs, which are connected through the relation. A sample response might look as follows:

{

"cis": [

{

"ucmdbId": "81e72bbac58df54a4ab8265f5475b2ae",

"type": "running_software",

"properties": {

"has_config_files": "false",

"root_candidatefordeletetime": "2016-11-16T03:25:39.077Z",

"data_operationisnew": "false",

"root_container_name": "(adv-desktop-101)",

"root_class": "running_software",

"TenantsUses": [

"System Default Tenant"

],

"data_operationstate": "0:Normal",

"display_label": "oracle_database (adv-desktop-101)",

"data_allow_auto_discovery": "true",

"discovered_product_name": "adv-Desktop-101_oracle_database",

"root_actualdeletetime": "2016-12-06T03:25:39.077Z",

"data_teststate": "0:Normal",

"root_container": "ada54c49ed057ebeb1c94dab1128c29c",

"application_ip_type": "IPv4",

"data_changecorrstate": "0:No Change",

"last_modified_time": "2016-10-19T01:21:58.092Z",

"create_time": "2016-10-18T07:42:16.776Z",

"TenantOwner": "System Default Tenant",

"data_changestate": "0:No Change",

"global_id": "58d61ef41f9b7b8c60210ba6fb8ab220",

"root_lastaccesstime": "2016-10-27T03:25:39.077Z",

"data_testisnew": "false",

“product_name": "oracle_database",

"root_iscandidatefordeletion": "false",

"data_source": "ServiceManager: DS_ServiceManager_SM Configuration Items Population job",

"data_changeisnew": "false",

"data_testcorrstate": "0:Normal",

"track_changes": "false",

"name": "adv-Desktop-101_oracle_database",

"data_operationcorrstate": "0:Normal",

"is_save_persistency": "false",

"data_adminstate": "0:Managed",

"data_updated_by": "Enrichment: Enrichment's rule:  SoftwareElementDisplayLabelForNewHost",

"root_enableageing": "false"

}

},

{

"ucmdbId": "ada54c49ed057ebeb1c94dab1128c29c",

"type": "node",

"properties": {}

}

],

“relations”: [

{

"ucmdbId": "f7d8ce1dfa59e3596c6dd8dde6c28384",

"type": "composition",

"properties": {

"root_candidatefordeletetime": "2016-11-16T03:25:39.077Z",

"last_modified_time": "2016-10-18T07:42:17.541Z",

"create_time": "2016-10-18T07:42:17.541Z",

"data_operationisnew": "false",

"data_changestate": "0:No Change",

"global_id": "f7d8ce1dfa59e3596c6dd8dde6c28384",

"data_testisnew": "false",

"root_lastaccesstime": "2016-10-27T03:25:39.077Z",

"root_class": "composition",

"data_source": "ServiceManager: DS_ServiceManager_SM Configuration Items Population job",

"root_iscandidatefordeletion": "false",

"data_changeisnew": "false",

"data_operationstate": "0:Normal",

"display_label": "Composition",

"data_testcorrstate": "0:Normal",

"data_allow_auto_discovery": "true",

"root_actualdeletetime": "2016-12-06T03:25:39.077Z",

"data_teststate": "0:Normal",

"data_operationcorrstate": "0:Normal",

"data_changecorrstate": "0:No Change",

"data_adminstate": "0:Managed",

“data_updated_by": "ServiceManager: DS_ServiceManager_SM Configuration Items Population job",

“root_enableageing": "false"

},

"end1Id": "ada54c49ed057ebeb1c94dab1128c29c",

"end2Id": "81e72bbac58df54a4ab8265f5475b2ae"

}

]

}

Run Impact Analysis via API

The UCMDB REST API provides an API endpoint which allows to run Impact Analysis and returns the affected CIs. Therefore you need to send a post request to the URL ‘http(s)://<baseurl>/rest-api/impactAnalysis’ and specify the impacted CIs as well as the severity of the impacts in the request’s post data (JSON).

The severity level need to be specified as a String value. The existing severity levels can either be requested by a get request to the ‘http(s)://<baseurl>/rest-api/impactAnalysis/severities’ URL (access token in header required) or extracted from the following list:

  • Normal
  • Warning(1)
  • Warning(2)
  • Minor(3)
  • Minor(4)
  • Minor(5)
  • Minor(6)
  • Major(7)
  • Major(8)
  • Critical

You can optionally specify one or more impact rule bundles in the post data, that only the impact rules from that bundles are applied (impact rules can be grouped in bundles). All bundles are used by default. Additionally, it is possible to specify attributes of the affected CIs, which shall be added to the response. A sample post data body in JSON format, where all rules are applied and the CI name is additionally requested, might look as the following:

{

              "triggerCIs": [

                             {

                                           "triggerId": "ada54c49ed057ebeb1c94dab1128c29c",

                                           "severity": "Minor(4)"

                             }

              ],

"bundles" : [],

              "properties": ["name"]

}

Make sure that the header of the request contains a valid access token from authentication endpoint and the content type is specified as ‘application/json’:

              {

‘Content-Type’ : ‘application/json’,
‘Authorization’ : ‘Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE0NzQzNT
c3MDYsImN1c3RvbWVyIjoxLCJ1c2VybmFtZSI6InN5c2FkbWluIn0.cVYsuum1CqaqfZV1K5KJ8nidOOif8Wv9tZsLFFZPbSs’

}

Do not forget to set ‘Bearer’ keyword in front of your token (see example above).

In case of a successful request, the response contains all the CIs, which are impacted by the given CI and the given severity. A sample response might look as follows:

{

    "affectedCIs": [

        {

            "ucmdbId": "ada54c49ed057ebeb1c94dab112e329c",

            "severity": "Minor(4)",

            "type": "node",

            "properties": {

                "TenantOwner": "System Default Tenant",

                "name": "adv-desktop-101",

                "TenantsUses": [

                    "System Default Tenant"

                ]

            }

       }

    ]

}

 

 

The UCMBD REST API also provides other endpoints to integrate additional UCMDB data. A full list of endpoints, features and recommendations can be found in the Developer Reference Guide from CMS Helpcenter.

 

 

  • configuration management
About the Author

Ops_Guest

Attachments