The Export API is available in yourCMDB >= 0.5

Other than the REST API, the ExportAPI pushes objects to other systems. There is a configuration file (exporter-configuration.xml), where you can define export tasks. Each export task has a unique name and consists of the following parts:

• sources
• destination
• variables

A source consists of multiple objects of a specific object type and a specific status. For example, all objects of type “router” that are active. You also can add constraints to that objects, for example, all active objects of type “router” that have the value “Cisco” in the field “manufacturer”, to get all Cisco routers. You can add multiple sources per export task.

A destination is an external system, where you want to push the yourcmdb objects. You need one destination per export task. For each destination you have to define a class that manages the communication to the external system. You can give parameters to the class, for example to add a hostname, username or password for your external system.

For each export task you can define variables. A variable has a name and gets its value out of fields of the objects. For example, you have a variable for an IP-address with the name “ip” and multiple sources. For the object type “router” the variable gets its value from the field “ip”, but for objects of type “switch”, it gets the value from the field from the field “ip-address”. See the configuration section below to get more details.

An export task is started by a script, which needs the name of the export task as a parameter. You can run the script as a cronjob to run an export task regularly.

To use the ExportAPI, you have to define export tasks in the configuration. After that, you can run export tasks by starting the exporter script.

The configuration of the ExportAPI is done in <yourcmdb-dir>/etc/exporter-configuration.xml file. In the following lines, you will find an easy example:

<exporter-configuration>
      <task name="example">
              <sources>
                      <source objecttype="router" status="A" fieldname="manufacturer" fieldvalue="Cisco" />
                      <source objecttype="switch" status="A" />
              </sources>
              <destination class="ExternalSystemDummy">
                      <parameter key="testparameter1" value="value1" />
                      <parameter key="testparameter2" value="valu2" />
              </destination>
              <variables>
                      <variable name="dummy1">
                              <value objecttype="router" fieldname="hostname" />
                              <value objecttype="switch" fieldname="management-ip" />
                      </variable>
                      <variable name="dummy2" default-value="0.0.0.0">
                              <value objecttype="router" fieldname="management-ip" />
                              <value objecttype="switch" fieldname="management-ip" />
                      </variable>
              </variables>
      </task>
<exporter-configuration>

Each export task is defined with <task>-tags and must have a unique name (here: “example”). A task must have sources, a single destination and optional variables.

Sources are defined with <sources>-tags. Within the <sources>-tags one or multiple sources can be defined by using the <source>-tag. A minimal source consists of objects of a specific object type and status (active/inactive). As an additional condition, you can use the value of a specific object field. See the examples below:

<!-- all active objects of type switch -->
<source objecttype="switch" status="A" />

<!-- all inactive objects of type switch -->
<source objecttype="switch" status="N" />

<!-- all active objects of type router, where the field "manufacturer" is set to "Cisco"-->
<source objecttype="router" status="A" fieldname="manufacturer" fieldvalue="Cisco" />

An export destination is defined within a <destination>-Tag. Until version 0.11, only one destination per task is allowed. In yourCMDB 0.12 and above, the definition of multiple <destination> blocks is possible. For each destination, a class must be defined using the class parameter. Optional, parameters (multiple key-value pairs) can be given to the destination class. For some destination classes, special parameters are needed. See the details in the documentation for the class. At the moment, the following destinations are implemented for yourCMDB:

You can set variables for your export tasks using in the <variables>-scection. See the example below:

<variable name="dummy2" default-value="0.0.0.0">
    <value objecttype="router" fieldname="management-ip" />
    <value objecttype="switch" fieldname="management-ip" />
</variable>

A variable is defined within a <variable>-tag and needs an unique name (e.g. dummy2) and has an optional default value. If defined in <value>-tags, the value of the variable is filled by a field of the particular object. For the example above, we defined a variable named “dummy2” with a default value “0.0.0.0”. For all objects of type “router” or “switch”, the value is defined by the field “management-ip”. Some of the destinations needs a special variables to be defined.

In version 0.14 or higher, you can use some special values as content in fieldname:

• yourCMDB_object_id
• yourCMDB_object_type

Please see the following example:

<variable name="hostvar_cmdbid">
    <value objecttype="server" fieldname="yourCMDB_object_id" />
</variable>

If you use fields of type objectref in your objects (see Configuration of object types for details), there are to ways to represent the data. Please have a look at the following example:

<variable name="dummy3" default-value="">
    <value objecttype="router" fieldname="location" />
</variable>
<variable name="dummy4" default-value="">
    <value objecttype="router" fieldname="location" refobjectfield="city"/>
</variable>
<variable name="dummy5" default-value="">
    <value objecttype="router" fieldname="location" refobjectfield="region.region-name" />
</variable>

Aussume that the field location of objecttype router has the type objectref-location. The value of variable dummy3 is the assetID for the referenced object, while the value of dummy4 is the content of the field city of the referenced object. Since version 0.14 you can define a path of multiple layered object references as described in the dummy5 example. So the field location of the router will be dereferenced, then field region will be used the derefence the next object and the content of the field region-name will be used.

Since version 0.6 you can use subfiles in your exporter-configuration.xml file:

<exporter-configuration>
      <includeconfig file="exporter/example.xml" />
      <includeconfig file="exporter/opennms-example.xml" />
</exporter-configuration>

Each <includeconfig> tag will be replaced with the given file.

To run an export task, use the <yourcmdb-dir>/scripts/exporter.php script in the follwing way:

./exporter.php <export taskname>
./exporter.php example

The script needs the name of an export task that is defined in your configuration. If you want to run an export task regularly, add the script as a cronjob.

Since version 0.11, you can use the REST API to start an export.