Tutorial

In this part of the documentation we discuss practical patterns for access, modifying and storing data in the cmdb.

Connect to the cmdb

We can connect to the cmdb by utilizing the configuration (See Configuration)

import cmdb_idoit as cmdb

cmdb.init_session_from_config()

or directly define access parameters in the code

import cmdb_idoit as cmdb

url = "https://cmdb.example.de/src/jsonrpc.php"
username = 'exampleuser'
password = 'examplepassword'
apikey = 'exampleapikey'

cmdb.init_session(url,apikey,username,password)

Loading Objects

Let us start with a simple example to access Objects. Therefore we first determine the object type constant. For this example we want all the servers, so the constant is C__OBJTYPE__SERVER. If you want another object type, see Commandline Interface.

The following will load all server objects and print their title.

servers = cmdb.CMDBObjects({'type': 'C__OBJTYPE__SERVER'})

for server in servers:
  print(server.title)

Accessing category data

Now we have all the servers, we can access category data by using the objects as dict with the category constants as keys. Accessing them directly will fetch the data on demand from the database. Each category itself is also accessible like an natural dict with a fixed key set.

for server in servers:
  print(server['C__CATG__GLOBAL']['title'])

If you are going access a lot of category data of the same category for several objects you should prefetch the dataset.

Prefetch category data for objects

servers.loadCategoryData('C__CATG__GLOBAL')

for server in servers:
  print(server['C__CATG__GLOBAL']['title'])

As an exercise try both variants and measure the time.

Handle multi value categories

Some object have so called multi value categories, hence have multiple instantiations of the same category. Those are represented as list so we can iterate over them.

::

servers.loadCategoryData(‘C__CATG__CONTACT’)

for server in servers:

print(server.title) for contact in server[‘C__CATG__CONTACT’]:

print(contact[‘contact’])

The above example will print a set of numbers, for each server. Those numbers are the object identifier for another object. If you want to more about the contact you have to load that object, it may have any possible object type.

Change an object

Every object has a cmdb_idoit.CMDBObject.title which can be manipulated without loading any further category data.

someserver = servers.pop()
someserver.title = "Some new title"
someserver.save()

We can of course manipulate other data, too.

someserver['C__CATG__GLOBAL']['title'] = "New Title"
someserver.save()

The above example will, save the new value. Even if you have not loaded the category data for C__CATG__GLOBAL.

Creating new objects

To create a new object, you do the following:

::

new_object = cmdb.CMDBObject(‘C__OBJTYPE__CONTACT’) new_object.title = “Some new title”

That’s it, now you are able to insert more data, as shown above.

Dealing with Dialogs

Many values in the i-doit web interface are predefined lists of selectable values, so called dialogs, e.g. the room type. In the API those attributes are represented as int. You can either define needed values in the Web Interface and view their int representation with the Commandline Interface utility or you define them in code and use the defined value directly.

cmdb_status = cmdb.CMDBDialog('C__CATG__GLOBAL','cmdb_status')
cmdb_status_planned = cmdb_status.get_dialog_from_const('C__CMDB_STATUS__PLANNED')

This example loads the dialog values for C__CATG__GLOBAL.cmdb_status and stores the value for the planned state into a local variable. The above variant is more language save than the code below, but the code below allows definition of dialog values in code. At the time of this writing there is no way to define constants for values like used above, you have to predefine them in the web interface.

cmdb_status_timetravel_value = "Wibbly Wobbly Timey Wimey"
cmdb_status.add(cmdb_status_timetravel_value)
cmdb_status_timetravel = cmdb_status.get_dialog_from_value(cmdb_status_timetravel_value)

someserver['C__CATG__GLOBAL']['cmdb_status'] = cmdb_status_timetravel
someserver.save()

The CMDBDialog object is aware of the available values, so readding them every time you run the code will not add them again. As long as you do not change the value.