Step By Step: How to Retrieve CIs Using REST API

This task includes the following steps:

1. Define Data

   Define the data you want to retrieve from UCMDB. For example, “I want to retrieve all nodes”. To achieve this, you need to create a new query which contains the CI types you are interested in.

   1. In UCMDB UI, go to Modeling > Modeling Studio to model the data.

   2. Click New > Query. A new Query modeling pane opens to the CI Types tab.

      

   3. Just drag and drop into the modeling pane the CI types you are interested in.

      

   4. Click Save .

      The Save Query dialog pops up. Save the query with a name by providing the name (for example, nodes_query) in the Query Name field.

   5. Return to the Resources tab. You to see all the queries here, most of them are out-of-the-box queries in a newly installed UCMDB.

   6. Double-click the query you just created to open it. In this example, double-click nodes_query.

      

   7. In the modeling pane you can count the results of your query by clicking Calculate Query Result Count .

      

      Calculating the TQL query is a good practice since it allows you to know that it has results.

      As you can see there exists two nodes.

2. Make REST calls and retrieve CIs

   1. Define two requests in SoapUI:

      1. One to authenticate which gives you back an authentication token
      2. Another one to retrieve query results.

      The second request uses response from the first one to authenticate.

      JSON response of the first request will look like this:

      {"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJyZXBvc2l0b3J5IjoiVUNNREIiLCJleHAiOjE1MDA0NTc0NDIsImN1c3RvbWVyIjoxLCJ1c2VybmFtZSI6InN5c2FkbWluIn0.6SO434meWazmfsOoSd-fXFaTFDx9QomOadalrgPpp8s"}

      You can extract the token value from the response above and put it along with the “Bearer” keyword into the Authorization header of the second request.

      Header value would look like: Bearer <token_value>

      As you can see in the screenshot below:

      

      Note There is a space between the keyword and the token value.

      Now you can make authenticated REST requests to UCMDB.

   2. Write the TQL query name into the message body.

      

      In the image above you also have the response which contains two CIs without any properties.

3. Additional properties knowledge base

   1. If you also want to see CIs' properties, go back to the Resources tab and double-click your query: nodes_query

      

   2. Select the CI in the modeling pane, then in the CI properties pane, go to the Element Layout tab and click Edit .

      The Query Node Properties dialog opens.

      

   3. Select the check box for Select attributes for layout.

      In the CI Types pane you can see your node type and all its subtypes. You can have different subtypes returning different attributes. In this example, let us stick to the main flow.

      

   4. Select Specific Attributes from the Attributes condition drop-down list, and then add the attributes you want to see in the result to the Specific Attributes tab.

      

   5. Click OK to save the changes.
   6. Click Save to save the TQL query.

   7. Now if you go back to your SoapUI and make the same request again with the same query name, you can also see the attributes.

      

      They appear in the response if they have a value.

   Note

   • Attention at how many attributes you add to your query. Each attribute you add will take processing power. The performance is inversely proportional with the number of attributes. If you are working with a light amount of data, you will barely see a difference. But when you have like millions of CIs, it will matter.
   • When updating a CI using the PUT method, the client should know that reconciliation engine attributes are not required. Reconciliation attributes are required just for CI creation.

Advanced Query Features

Query node can also have condition on different kind of properties, so just specific instances of some CI types appear depending on the created conditions.

TQL queries are composed of nodes and relations, in real world entities have many different kind of relations with other entities, and you can also query those types of structures.

In addition to the main feature described here, there are more advanced features available with UCMDB.