Skip to content

CMDB Structures

CMDB Structures is a useful feature of i-doit up's add-on architecture. It allows add-ons to require several CMDB structures to function correctly without the necessity to send the corresponding API calls manually.

Advantages#

The main reason of introducing CMDB Structures was to make it as easy as possible to require CMDB structures for add-ons. Nevertheless, it is still possible to create these resources over the API during the registration procedure for example. Unfortunately this requires knowledge of i-doit up's backend API and impedes the accessibility of such structures. Another disadvantage for add-on developers is that they have to react on API changes which might happen in the future and would require an update of their add-on. By using CMDB Structures this responsibility can be shifted to i-doit up to not be forced to react on these changes. Another valuable feature of CMDB Structures is its ability to perform updates on these structures safely.

Supported Structures#

Add-ons can require the following CMDB structures:

  • Categories and properties
  • Classifications
  • Collections

How to use?#

CMDB structures are placed in addon.json. During registration and update procedure the addon.json will be interpreted by i-doit up. If i-doit up finds a cmdb section it will start a procedure to reflect these definitions to its CMDB structures.

1
2
3
4
5
6
7
8
9
{
    "title": "My special add-on",
    "identifier": "my-special-addon",
    […]
    "cmdb": {
        # Definition of add-on specific cmdb structures
        […]
    }
}

Categories and properties#

Categories and properties are strictly linked. Therefore, properties are embedded into category definitions. Categories will be defined in categories key. The following is an example definition of a category and its properties:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
    "cmdb": {
        "categories": [
            {
                # ID of category
                "id": "host_status",
                # Title of category
                "title": "Host status",
                # Multivalue Yes/no
                "multivalue": true,
                # Properties of category
                "properties": [
                    {
                        # ID of property
                        "id": "url",
                        # Title of property
                        "title": "URL",
                        # Type of property
                        "type": "text"
                    },
                    […]
                ]
            },
            # more categories…
            […]
        ]
    }
}

Categories#

A category definition consist of four essential information:

  • id: This identifier will be used to generate the id of the category. The finalid will be composed like addon.vendor.addon.id.category.id
  • title: This information declares the title of the category and its naming
  • multivalue: This will enable you to mark the category as multivalue to allow multiple entries for each object. Please check CPU and Accounting categories to understand the difference.
  • properties: This key holds all related properties of the category

Properties#

As mentioned properties are an embedded part of the category definition. A property consists of three simple information:

  • id: The property id is only for composition. The final id will consist of addon.vendor.addon.id.category.id.property.id
  • title: The title defines the naming of the property
  • type: The type indicates the behavior and functionality of a property

The following section describes the most common types:

  • text: Simple text input
  • multiline-text: Multi-line text input with larger capacity and better handling in the UI
  • number: Simple number field - can hold integers and floats
  • bool: Simple Yes/No field to query boolean information
  • object: Allows references between two objects

A full list of possible types can be retrieved over i-doit up's API: http://my.docupike.com/api/v2/property-type. As result, you will get all available property types in your i-doit up instance.

Limitations#

The CMDB feature allows you to define categories and attributes within the scope of the add-on. As result, you cannot alter the categories/attributes outside the add-on's scope - predefined, user-defined, coming from other add-ons.

  • You cannot update base information of existing categories
  • You cannot add custom properties to existing categories
  • You cannot update type of existing properties - this is a general constraint!

Classifications#

Classifications are also manageable by CMDB Structures. You can define them in classes key:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
{
    "cmdb": {
        "classes": [
            {
                # ID of class
                "id": "air_plane",
                # Title of class
                "title": "Air plane",
                # Icon of class
                "icon": "airplane",
                # List of category ids assigned to class
                "categories": [
                    "cmdb.access",
                    "cmdb.formfactor"
                ],
                # List of objects for defined class
                "objects": [
                    "object-id-1": {
                        "title": "Example object1"
                    },
                    "object-id-2": {
                        "title": "Example object2"
                    }
                ]
            }
        ]
    }
}
  • id: The id of the class - the final id will consist of addon.vendor.addon.id.class.id
  • title: The title attribute defines its naming in the UI and is the human-readable presentation of the class
  • icon: The icon cannot refer to external resources and have to reference built-in resources from i-doit up
  • categories: Definition of assigned categories by using full ids of categories
  • objects: Definition of objects for class

Objects#

The CMDB feature allows add-on developer to predefine objects. The objects can be added to defined classes. The most simple example is an object with a title (see above). Also, it's possible to define entries within object using data key:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
{
    "object-id-1": {
        "title": "Example object1",
        "data": {
            "cmdb.address": {
                "one": {
                    "streetAddress": "Musterstr 9",
                    "postCode": "40234",
                    "country": "Germany",
                    "city": "Düsseldorf"
                }
            },
            "cmdb.cpu": {
                "one": {
                    "cores": 2,
                    "vendor": "Intel",
                    "model": "i123"
                },
                "two": {
                    "cores": 2,
                    "vendor": "Intel",
                    "model": "i123"
                }
            }
        }
    },
    "example-id-2": {
        "title": "Example object2"
    }
}
  • data: The data attribute defines entries for some categories ("cmdb.address" and "cmdb.cpu" in this example). The data for every entry includes the values for the properties.

Updating existing classes#

There is also the possibility to update existing classes of i-doit up by using ref_id. A common use case for this case is to add a custom category to i-doit up's stock classes. In this case all defined categories will be added to the existing assignments. The ref_id should include the class constant. To find out the constant of a class you can use the API and open http://my.docupike.cloud/api/v2/class. This will give you a full list of all available classes and also the constant information.

Collections#

Collections can be also created and updated in a declarative way. The following should give you an idea how to define collections:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
{
    "cmdb": {
        "collections": [
            {
                # ID of collection
                "id": "furniture",
                # Title of collection
                "title": "furniture",
                # List of class constants assigned to collection
                "classes": [
                    "chair",
                    "table"
                ]
            }
        ]
    }
}

Updating existing collections#

Like classes, collections can also reference stock resources of i-doit up to update its attributes. You can use ref_id, which is simply the title of the collection. You can get a list of all collection's and their ids over the API: http://my.docupike.cloud/api/v2/collection

Limitations#

There are some limitations which might require to use the API:

  • You cannot reference custom classes