Share This:

As most of you are aware, we are still shipping CMDBDRIVER program along with CMDB REST API to perform several operations including retrieving and sending data.  CMDB C API functions and CMDB  REST API provide similar data structures and functions to encapsulate information and functionality. Additionally, the web services API provides a set of platform-independent operations that communicate with your applications to retrieve and send data.

As the knowledge of these two component  is vast, I want to narrow down the scope of this blog to the following:.

Topics Covered in this blog:

[a]  A brief introduction of CMDBDRIVER tool & CMDB REST API services

[b]  A list of a few important REST API and the corresponding C API functions in CMDBDRIVER command-line tool

[c]  How to access CMDB REST API in BMC CMDB?

           [d]  How to consume CMDB REST API?

      [d.a] First, Generate an AR JWT token using tools like POSTMAN

      [d.b] Consume the CMDB REST API in POSTMAN or Swagger UI using the AR JWT token you generated in step ‘d.a’

 

Topics Not Covered in this blog:

[a] Configuring HTTPS on Jetty web server (offering CMDB REST API services)

[b] Integrating Remedy SSO with Configuration Management Dashboard

[c] REST API services other than CRUD operations for CMDB class ‘instance’

[d] Details of CMDBDRIVER commands

 

[a] A brief introduction of CMDBDRIVER tool & CMDB REST API services

 

CMDBDRIVERThe cmdbdriver program enables you to execute various BMC Atrium Configuration Management Database (BMC Atrium CMDB) C application programming interface (API) functions. You can combine several cmdbdriver commands in a script that you can execute with a single command. This combination is helpful when you need to reuse a series of commands.

https://docs.bmc.com/docs/ac9000/cmdbdriver-program-509980235.html

CMDB REST API: 

REpresentational State Transfer (REST) is a technique / architecture using which a user-friendly web-service for an Web application can be created..  We aren’t creating any REST API using BMC CMDB, but will be using the ones shipped by it.

You can use, both, the C & the REST API functions to perform the following operations in BMC CMDB

  • Create, modify, retrieve, delete classes.
  • Create, modify, retrieve, delete attributes
  • Create, modify, retrieve, delete instances
  • GraphWalk/GraphQuery
  • QueryByPath
  • Import/Export class/attributes/instances
  • Start/cancel/get RE jobs
  • Retrieve/activate federation

[b] A list of a few important REST API and the corresponding C API functions in CMDBDRIVER command-line tool

 

C API

REST API

Description

get (gi)

GET /cmdb/v1.0/instances/{datasetId}/{namespace}/{className}/{instanceId}

Gets single instances of a class for a given dataset

getmult (gmi)

GET /cmdb/v1.0/instances/{datasetId}/{namespace}/{className}

Gets multiple instances of a class for a given dataset

set (si)

PATCH /cmdb/v1.0/instances/{datasetId}/{namespace}/{className}/{instanceId}

Updates a single instance of a class for a given dataset for a given instance Id

setmult (smi)

PATCH /cmdb/v1.0/instances/{datasetId},

PATCH /cmdb/v1.0/instances,

PATCH /cmdb/v1.0/instances/{datasetId}/{namespace}/{className}

Updates multiple instances of a class

create (ci)

POST /cmdb/v1.0/instances

Can be used to create a single or multiple instances in a class

createmult (cmi)

POST /cmdb/v1.0/instances

POST /cmdb/v1.0/instances/{datasetId}

POST /cmdb/v1.0/instances/{datasetId}/{namespace}/{className}

Create multiple instances

delete (di)

DELETE /cmdb/v1.0/instances/{datasetId}/{namespace}/{className}/{instanceId}

Delete a single instance

deletemult (dmi)

DELETE /cmdb/v1.0/instances

DELETE /cmdb/v1.0/instances/{datasetId},

 

DELETE /cmdb/v1.0/instances/{datasetId}/{namespace}/{className}

 

Delete multiple instances

get (gc)

GET /cmdb/v1.0/classes/{namespace}/{className}

Returns a CDM class for given namespace name and class name

set (sc)

PATCH /cmdb/v1.0/classes/{namespace}/{className}

Modifies the given class

create (cc)

POST /cmdb/v1.0/classes/{namespace}/{className}

Creates a class

delete (dc)

DELETE /cmdb/v1.0/classes/{namespace}/{className}

Deletes a class as per the inputs given

getlist(glc)

GET /cmdb/v1.0/classes/{namespace},

GET /cmdb/v1.0/archivedclasses,

GET /cmdb/v1.0/classes,

GET /cmdb/v1.0/classes/archiveinfo/{namespace}/{className},

GET /cmdb/v1.0/classes/relationships

Get a list of classes

get (ga)

GET /cmdb/v1.0/attributes/{namespace}/{className}/{attributeName},

GET /cmdb/v1.0/attributes/{namespace}/{className}

Two separate commands to get a single and multiple attributes for a class, first one for a single and the second for a multiple attributes

set (sa)

PATCH /cmdb/v1.0/attributes/{namespace}/{className}/{attributeName},

PATCH /cmdb/v1.0/attributes/{namespace}/{className}

Two separate commands to update a single and multiple attributes for a class, first one for a single and the second for  multiple attributes

create (ca)

POST /cmdb/v1.0/attributes/{namespace}/{className}/{attributeName},

POST /cmdb/v1.0/attributes/{namespace}/{className}

Two separate commands to create a single and multiple attributes for a class, first one for a single attribute and the second for multiple attribute

 

[c] How to access CMDB REST API in BMC CMDB?

REST API is hosted on Jetty server, and is installed and configured on AR Server.

jetty-server name is your AR server host name

The Jetty web server can be configured to serve on HTTPS protocol too.   CMDB REST API services are available on GET, POST, PATCH and DELETE methods.

Swagger UI:

The REST API provides certain endpoints that are aligned with the Swagger specification language.   The Swagger UI shows all the endpoints provided by CMDB REST API.  The URL for accessing Swagger UI is following:

http://<jetty-server>:8008/cmdb/api/help.html

The above URL when launched in a browser session will present the page that allows authorization to Swagger Tool using the pre-authenticated AR-JWT Token

Upon successful authorization into Swagger tool, the page will display the list of all the available BMC CMDB REST API services for consumption purposes. – see the below pic

Authorising to Swagger tool.PNG

[d] How to consume CMDB REST API?

[d.1] First, Generate an AR JWT token using tools like POSTMAN

Video: https://www.youtube.com/watch?v=xue9Gx-dbEA&feature=youtu.be

Note: When using POSTMAN tool to authorize the user, please use the user credentials parameters as seen in the below picture. I’ve noticed it failing with HTTP 500 error if the parameter names vary.  So, the parameters are 'username' and 'password'

CREATEMultipleInstance Part 1.PNG

Another point to note is that the video shows Jetty server is hosted on port 8443, but the default port it 8008.

URL:      http://<jetty server name>:8008/api/jwt/login

[d.1] Consume the CMDB REST API in POSTMAN or Swagger UI using the AR JWT token you generated in step ‘d.1’

Below picture shows the available CRUD operations for instances

CRUD Instance available REST API.PNG

Note: I’ve used 4 examples below to demonstrate the use of CRUD (Create, Read, Update & Delete) operations for CMDB Class instances (Configuration Items);  I’ve used POSTMAN tool for CREATE, UPDATE and DELETE operations, and used SWAGGER UI for GET operation – to show the use-cases in both the tools.

 

Example 1 – Done using POSTMAN – Create multiple instances of a class for a given dataset (4 steps)

Example 2 Done using SWAGGER tool - Gets a single instance of a class for a given dataset for a given Instance Id (1 step – follow the pic)

Example 3 Done using POSTMAN  - Update an instance (4 steps)

Example 4 Done using POSTMAN  - Delete an instance (4 steps)

 

Example 1 – Done using POSTMAN – Create multiple instances of a class for a given dataset

 

[Step  1] Generate an Authorization code (you may use the one created in the step 'd.1' if it is still valid)

     REQUEST URI: http://<jetty-servername>:8008/api/jwt/login

  Method: POST

 

After filling out the parameters as seen in the screen, please click ‘Send’ command button

 

CREATEMultipleInstance Part 1.PNG

[Step  2] Create another POST request in a separate tab within POSTMAN tool, in order to configure HEADERS for the CREATE INSTANCE request

     Method: POST
 REQUEST URI:   http://<jetty-servername>:8008/api/cmdb/v1.0/instances/<datasetID>
 
       Example: http://testserver:8008/api/cmdb/v1.0/instances/BMC.ASSET

CREATEMultipleInstance Part 2.PNG
Fill out 'Authorization' with the AR JWT token that you generated in the previous step or step 'd.1', and 'Content-type' & 'Accept' with 'applicatio/json' respectively

[Step 3] Switch to the ‘Body’ tab within the same request, and paste the following string. 

And then click the ‘SEND’ button

{

"instances": [

    {

"class_name_key": {

        "name": "BMC_ComputerSystem",

"namespace": "BMC.CORE"

},

"attributes": {

"Name": "Amazon Cloud VM",

"ShortDescription": "Amazon Cloud VM"

}

    },

    {

"class_name_key": {

"name": "BMC_ComputerSystem",

"namespace": "BMC.CORE"

},

"attributes": {

"Name": "Amazon Cloud VM 1",

"ShortDescription": "Amazon Cloud VM 1"

}

    },

    {

"class_name_key": {

"name": "BMC_ComputerSystem",

"namespace": "BMC.CORE"

},

"attributes": {

"Name": "Amazon Cloud VM 2",

"ShortDescription": "Amazon Cloud VM 2"

}

    }

  ]

}

 

CREATEMultipleInstance Part 3.PNG

 

[Step 4]  Search the newly created instances in BMC_ComputerSystme class

 

Example 2 – Done using SWAGGER tool - Gets a single instance of a class for a given dataset for a given Instance Id

 

NOTE: When consuming the REST API service by referring to the following examples, please click ‘Try it out' button after filling out the parameter values. 

Instance GET part 1.PNG

Instance GET part 2.PNG

Instance GET part 3.PNG

 

Example 2.a – Gets multiple instances of a class for a given dataset – Please note to specify multiple instanceid in ‘id’ parameter separated each by comma. - Click 'Try it out' button after you have filled out all the parameters

GetMultipleInstance Part 1.PNGGetMultipleInstance Part 2.PNG

GetMultipleInstance Part 3.PNG

 

Example 3 Done using POSTMAN  - Update an instance

METHOD:  PATCH

REQUEST URI: http://<servername>:8008/api/cmdb/v1.0/instances/<datasetID>
 
Example: http://testserver:8008/api/cmdb/v1.0/instances/BMC.ASSET
 

[STEP 1]  GENERATE AUTHORISATION CODE (you may use the one created in the step 'd.1' if it is still valid)

      REQUEST URI: http://<jetty-servername>:8008/api/jwt/login

  Method: POST

           Fill out user credentials as seen in the below pic, and then click Send button

CREATEMultipleInstance Part 1.PNG

 

[STEP 2]  Create another PATCH request in a separate tab within POSTMAN tool, in order to configure HEADERS for the UPDATE INSTANCE request

UpdateMultipleInstances Part 1.PNG

Fill out 'Authorization' with the AR JWT token that you generated in the previous step or from step 'd.1', and 'Content-type' & 'Accept' with 'applicatio/json' respective

[STEP 3]  CONFIGURE BODY TEXT:  Switch to the Body tab.   Sample body text below – Alter the ‘instance_id and other details based on your example, copy it in the Body, and click Send button

{"instances":[{"instance_id":"OIGAA5V0FLJHWAQ1CGR5Q1CGR5PU93","class_name_key":{"name":"BMC_ComputerSystem","namespace":"BMC.CORE","_links":{}},"dataset_id":"BMC.ASSET","attributes":{ "Name": "Azure Cloud VM", "ShortDescription": "Azure Cloud VM"},"_links":{}}],"num_matches":1}

 

UpdateMultipleInstances Part 2.PNG

Click the SEND button once the BODY, HEADERS and REQUEST URI is populated

[STEP 4] VERIFY THE UPDATED INSTANCE IN THE CLASS

 

Example 4 Done using POSTMAN  - Delete an instance

 

METHOD:  DELETE

REQUEST URI: http://<servername>:8008/api/cmdb/v1.0/instances/<datasetID>

Example: http://testserver:8008/api/cmdb/v1.0/instances/BMC.ASSET

[STEP 1]  GENERATE AUTHORISATION CODE

Fill out user credentials as seen in the below pic, and then click Send button (you may use the one created in the step 'd.1' if it is still valid)

CREATEMultipleInstance Part 1.PNG

[STEP 2]  Create another DELETE request in a separate tab within POSTMAN tool, in order to configure HEADERS for the UPDATE INSTANCE request

DeleteSingleInstance part 2.PNG

Fill out 'Authorization' with the AR JWT token that you generated in the previous step or from step 'd.1', and 'Content-type' & 'Accept' with 'applicatio/json' respective

[STEP 3]  CONFIGURE BODY TEXT:  Switch to the Body tab.   Sample body text below – Alter the ‘instance_id and other details based on your example, copy it in the Body, and click Send button

{"instances":[{"instance_id":"OIGAA5V0FLJHWAQ1CO5FQ1CO5FQD08","class_name_key":{"name":"BMC_ComputerSystem","namespace":"BMC.CORE","_links":{}},"dataset_id":"BMC.ASSET","_links":{}}],"num_matches":1}

DeleteSingleInstance part 3.PNG

[STEP 4] VERIFY THE DELETED INSTANCE IN THE CLASS