Data collector for OCS Inventory

This stand-alone application collects information from a single OCS Inventory NG server in order to populate the iTop CMDB with the collected Servers, PCs and Virtual machines. The collector uses the iTop data synchronization engine to synchronize the information between OCS Inventory and iTop.

An additional extension Data model for OCS Inventory is mandatory in iTop. It adds some fields needed for synchronization and displays the contents of the OCS inventory pages directly from iTop, for each synchronized object (Server, PC, Mobile phone or Virtual Machine):

• Automated inventory of Brand, Model, OS Family, OS Version, OS Licence, Physical Server, PC, Virtual Machine, Mobile Phone, Printer, Software from OCS Inventory server
• Automated inventory of Network Interfaces
• The collector can reside on any system with web access to iTop and mysql access to the OCS Inventory server
• Automatic creation and update of the Synchronization Data Sources in iTop.
• It is necessary to install the small extension Data model for OCS Inventory which adds some fields and an “OCS Inventory” link on synchronized PCs, Servers, Virtual Machines, Mobile Phones and software. This link opens a new tab with the OCS page of the device.

• The collector is not normalizing Model, OS Family and OS Version
• The collector synchronizes only PCs and Servers which have a valid serial number in OCS
• If IP collection is enabled, only IPv4 addresses are collected, not IPv6
• There is no single sign-on between iTop and OCS, so you will need to log in to OCS when you display the OCS tab

• PHP Version 7.2.0
• An access to the OCS Inventory NG mysql database
• An access to the iTop web services (REST + synchro_import.php and synchro_exec.php). Note: starting with iTop 2.5.0, the user must have the profile REST Services User in iTop.
• + Data collector Base requirements.
• If you have ocs collector v1, you need go to database in order to rename some tables (XX replace id in corresponding datasource in iTop):
  • synchro_data_pc_XX to synchro_data_pc_ocsng
  • synchro_data_server_XX to synchro_data_server_ocsng
  • synchro_data_virtualmachine_XX to synchro_data_virtualmachine_ocsng

Later, if you have some synchronization problem due to table name, you need to rename the table which starts with synchro_data_ and ends with synchro data source id with name seen in synchro data source object.

By example, in this case :

you have to rename the table synchro_data_physicalinterface_171 to synchro_data_pcphysicalinterface_ocsng

• Expand the content of the zip archive “ocsng-data-collector” in a folder on the machine that will run the collector application. This machine must have an SQL access to the OCS NG database and a web access to the iTop server.
• Create the file conf/params.local.xml according to your installation, providing the appropriate credentials to connect to OCS NG and iTop.

By default this file should contain the values used to connect to the iTop server and the OCS NG server:

<parameters>
  <itop_url>http://localhost/</itop_url>
  <itop_login>admin</itop_login>
  <itop_password>admin</itop_password>
  <contact_to_notify>john.doe@demo.com</contact_to_notify>
  <synchro_user>admin</synchro_user>
  <sql_host>localhost</sql_host>
  <sql_database>ocsweb;charset=UTF8</sql_database>
  <sql_login>root</sql_login>
  <sql_password>root</sql_password>
</parameters>

By default the data collection configuration is defined in the file collectors/params.distrib.xml. Do not modify this file! If you need to adapt the configuration, create a file named params.local.xml in the conf directory and copy/paste the needed definitions into it (the structure of both XMl files is the same). This configuration defines the SQL queries that must be executed on the OCS NG server to retrieve data and synchronise it with iTop.

   <!-- default values -->
    <default_org_id>Demo</default_org_id>
    <default_status>production</default_status>
    <default_active_status>active</default_active_status>
   <!--Filter type for synchronization ( categories or default filters ) -->
    <use_asset_categories>yes</use_asset_categories>
    <use_software_categories>yes</use_software_categories>    
   <!-- Class to collect -->
    <CategoryCollection>yes</CategoryCollection>
    <PCCollection>yes</PCCollection>
    <ServerCollection>yes</ServerCollection>
    <VMCollection>yes</VMCollection>
    <MobilePhoneCollection>yes</MobilePhoneCollection>
    <PrinterCollection>yes</PrinterCollection>
    <SoftwareCollection>yes</SoftwareCollection>

This parameters allow to activate or desactivate a group of collectors. If you want to disable one collector in a group, you can do so in collectors_launch_sequence (cf Data collector Base mechanism).

• For each class of object to import into iTop (PC, Server, VM, Brand, Model, OSVersion OSFamily), a Synchro Data Source is created by the collector application.
• Each collector is associated with an SQL query (via the parameter <name_of_the_collector>_query).
• This query must return column where aliases (i.e. “name” of the columns) correspond to the expected fields for the corresponding Synchro Data Source.
• These queries can be adapted to suit your needs (for example to better differentiate PCs and Servers or to change/set some default values for some columns)
• Since the synchronization of PCs, Servers and Virtual Machines all rely on their own SQL query, it is important to make sure that the results of these 3 queries do no overlap. Otherwise the same “system” will be imported several times in itop (for example as both a PC and a Server).
• You can use OCS categories in order to synchronize assets and softwares. In this case, you must create categories in OCS and create corresponding objects AssetCategories and SoftwareCategories in iTop. You can use synchronisation in order to help you to create this objects.

During the process, some of the following queries are executed depending on your parameters. If use_asset_categories = yes only queries with “with_categories” are executed. If use_asset_categories = no only corresponding queries without “with_categories” are executed.

These queries can be redefined in the file conf/params.local.xml in order to take into account your specific needs (For instance change status of created Server, PC, Virtual Machine, as well as default organisation).

• Collector will discover all Cis resulting of SQL queries not ending by _with_categories_query defined in config file.
• Indicate in configuration file

use_asset_categories = no
<CI>Collection= yes (replace CI by required collected class)

If you use synchronisation with assets categories, you have to configure the same assets categories both in OCS and in iTop. You can have many categories for one asset type.

First configure assets categories in OCS thanks to search menu below Inventory choice

Verify that assets correspond to your request and create your category thanks to this search.

You can see your assets categories in menu:

In order to have the same results as with default params, you can create this categories:

Asset categories are in typologie menu.

You have to create categories exactly with the same names as in OCS and parameter in which class there are collected. If you use categories collector, you only have to indicate the target class.

Finaly you have the same list in the both environment

• Create softwares in iTop. Collector will try to discover all defined softwares in iTop.
• Indicate in configuration file

SoftwareCollection= yes
use_software_categories= no

Collector will collect from OCS software's names defined in iTop

If you use synchronisation with software categories, you have to configure the same software categories both in OCS and in iTop. You can have many categories for one software type. You will need to

• define in OCS, categories on all sofwtares you want to collect
• execute collector to have OCS catgeories synchronised in iTop
• map target class to each categorie synchronised
• execute again collector to receive categorised OCS CIs.

First configure software categories in OCS thanks to Software Category menu below Manage

Click on New Category and give a name to your category

Then click on Add software. Select your category and add a software name or a regexp

You can add many regexp on a software category. You can seen the list in List of regexp

The list of all software in a category can be seen in List of categories

Software categories are in typologie menu.

You have to create categories exactly with the same names as in OCS and parameter in which class there are collected. If you use categories collector, you only have to parameters the corresponding class.

The collector automatically detects if TeemIp is present on the remote iTop application (as a module or even as a stand-alone application) and if TeemIp Zone Management extension is installed. Should that be the case, then the following parameters may trigger IP addresses and IP interfaces collection.

<?xml version="1.0" encoding="UTF-8"?>
  <parameters>
    ...
    <!-- TeemIp options -->
    <IPCollection>yes</IPCollection>
    <default_ip_status>allocated</default_ip_status>
    <manage_ipv6>no</manage_ipv6>
    <default_view_name></default_view_name>
    ...
  </parameters>

To launch the data collection and synchronization with iTop, run the following command (from the root directory where the data collector application is installed):

php exec.php

The following (optional) command line options are available:

The execution of the command line will:

1. Connect to iTop to create the Synchronization Data Sources (or check their definition if they already exist, updating them if needed)
2. Connect to OCS NG to collect the information about the Servers, PC, Virtual Machines
3. Upload the collected data into iTop (this is the configuration parameter <name_of_the_collector>_query
4. Synchronize the collected data with the existing iTop CIs.

Once you've run the data collector interactively, the next step is to schedule its execution so that the collection and import occurs automatically at regular intervals.

The data collector does not provide any specific scheduling mechanism, but the simple command line php exec.php can be scheduled with either cron (on Linux systems) or using the Task Scheduler on Windows.

Question: how can I add OCS classes to the collection plan
Answer: Other classes than the ones listed by default in the collector can be added to it. For that purpose, we highly recommend to use the extensibility mechanism that is available since version 2 of the collector (version 1.3.0 of iTop Data Collector Base).

• Make sure the class (MyNewClass) has been modelized in iTop (Through the Data model for OCS inventory extension for instance).
• Within the <your_collector>/collectors/extensions/ directory:
  • Create a params.distrib.xml file
    • Add a class entry in it, like what is done in the default section,
    • Add a extensions_collectors_launch_sequence similarly to what is done in the Class Collection Sequence section,
  • Create the json/MyNewClassOCSCollector.json file that describes the synchro data source of the new class,
  • Create the src/MyNewClassOCSCollector.class.inc.php file that contains the collector specificities for the class (REST API URL, dependency parameters…),
• And that's it