Data collector for InTune

This collector enables administrators to automatically feed iTop with relevant and accurate InTune cloud computing information. Together with the InTune modelization that the Data model for Microsoft InTune extension brings, it links iTop CMDB to the InTune world.

The Data collector for InTune is a stand-alone PHP software that connects to InTune, retrieves managed devices and synchronizes them with iTop's CMDB.

• Connection to InTune is done through Graph OAUTH2 authentication,
• Objets'retrieval relies on Graph REST API which extracts data in JSON format,
• Synchronization follows iTop's built-in Data Synchronization mechanism.

For better integration with inTune, the collector may work in conjunction with the Data model for Microsoft InTune extension that can be installed on iTop where iTop objects commonly used in the Microsoft platform are enriched with InTune attributes.

The Data collector for InTune synchronizes the following objects:

• Brands
• Models
• OS families
• OS versions
• Mobile Phones
• PCs
• Tablets

The main problem with that synchronization is that InTune devices are not typed as PCs, tablets, mobile phones or anything else. They are just managed Devices ! It is, therefore, up to the collector to find out this information, based by default on the information already stored in iTop, or also based on its configuration files. Note that the Data model for Microsoft InTune extension helps with that task.

Data collection can be enhanced by adding further InTune classes to this list. Please, refer to the Q&A section below.

The collector only synchronizes devices managed by InTune (see above).

To use the collector, a few points must be observed:

• The InTune managed devices synchronized by the collector must exist in iTop (CMDB CIs). This is, by default, the case with iTop's standard data model as long as the End-User Devices management extension has been selected.
• In order to browse InTune's computing environment, you'll need a Graph account (see service principal) that allows you to read InTune's resources.
• From a system standpoint, you'll need to comply with the requirements expressed in the Data collector Base documentation.
• Modelization of managed devices may be enhanced with a set of attributes defined in the Data model for Microsoft InTune extension. Please, refer to the Q&A section for furhter details on that question.

Simply expand the content of the zip archive into a folder on the machine where the collector will be run.

The configuration of the application is built by concatenating 4 files:

1. collectors/params.distrib.xml that holds the entries that are specific to the Data collector for InTune. It should not be modified.
2. collectors/extensions/params.distrib.xml that holds entries that have been created and added by the customer to answer its specific needs. This file is optional.
3. conf/params.distrib.xml that is provided by the collector framework, Data collector Base. It should not be modified.
4. conf/params.local.xml where the collector can be adapted to the specific customer needs.

The collectors/params.distrib.xml configuration file holds parameters that must (for some) or can (for others) be changed when configuring the collector, which is done through the conf/params.local.xml file.

<?xml version="1.0" encoding="UTF-8"?><!-- Default values for parameters. Do NOT alter this file, use params.local.xml instead -->
<parameters>
        <!-- Microsoft links -->
        <microsoft_login_url>https://login.microsoftonline.com/</microsoft_login_url>
        <microsoft_auth_mode>/oauth2/token</microsoft_auth_mode>
        <microsoft_resource>https://graph.microsoft.com/</microsoft_resource>
 
        <!-- Client's credentials -->
        <ms_clientid></ms_clientid>
        <ms_clientsecret></ms_clientsecret>
        <ms_tenantid></ms_tenantid>
        <ms_tenantid_short></ms_tenantid>
 
        <!-- *** iTop Class Parameters *** -->
        ...
           List of iTop classes with their parameters, including their InTune matching fields
        ...
 
        <!-- Class collection sequence -->
        ...
           List of classes to collect with the rank in the collection process
        ...
 
        <!-- Global iTop parameters -->
        <model_unknown_type>InTuneUnknown</model_unknown_type>
 
        <!-- Synchronization parameters -->
        <contact_to_notify></contact_to_notify>
        <synchro_user></synchro_user>
        <name_prefix>InTune</name_prefix>
        <name_postfix>Discovery</name_postfix>
        <json_placeholders>
                <itopbrand_synchro_name>$name_prefix$ Brands $name_postfix$ - $ms_tenantid_short$</itopbrand_synchro_name>
                <itopmodel_synchro_name>$name_prefix$ Models $name_postfix$ - $ms_tenantid_short$</itopmodel_synchro_name>
                <itoposfamily_synchro_name>$name_prefix$ OS Families $name_postfix$ - $ms_tenantid_short$</itoposfamily_synchro_name>
                <itoposversion_synchro_name>$name_prefix$ OS Versions $name_postfix$ - $ms_tenantid_short$</itoposversion_synchro_name>
                <itopmobilephone_synchro_name>$name_prefix$ Mobile Phones $name_postfix$ - $ms_tenantid_short$</itopmobilephone_synchro_name>
                <itoppc_synchro_name>$name_prefix$ PCs $name_postfix$ - $ms_tenantid_short$</itoppc_synchro_name>
                <itoptablet_synchro_name>$name_prefix$ Tablets $name_postfix$ - $ms_tenantid_short$</itoptablet_synchro_name>
                <synchro_status>production</synchro_status>
                <full_load_interval>0</full_load_interval><!-- 7 days (in seconds): 7*24*60*60 -->
                <!-- Set the following parameters to 1 if you want to update them, to 0 otherwise -->
                <update_mobilephone_contacts_list>1</update_mobilephone_contacts_list>
                <update_pc_contacts_list>1</update_pc_contacts_list>
                <update_tablet_organization>1</update_tablet_organization>
        </json_placeholders>
 
</parameters>        

The collectors/extensions/params.distrib.xml configuration file holds parameters to collect additional classes required by a customer.

<?xml version="1.0" encoding="UTF-8"?><!-- Default values for parameters. Do NOT alter this file, use params.local.xml instead -->
<parameters>
        <!-- iTop Class Parameters -->
        ...
           List of additional iTop classes with their parameters, including their InTune matching fields
        ...
 
        <!-- Class collection sequence -->
        ...
           List of additional classes to collect with the rank in the collection process
        ...
 
 
        <!-- Synchronization parameters -->
        <json_placeholders>
                <itopmyclass_synchro_name>$name_prefix$ My Class $name_postfix$</itopmyclass_synchro_name>
                ...
                   Placeholders for other additional classes
                ...
        </json_placeholders>
 
</parameters>

This set of parameters is required to connect to the iTop application or the Microsoft InTune environment. Some of them must or may be adapted to meet customer's environment.

These are parameters related to the iTop datamodel.

The parameters that are defined in this section will directly alter the content of the json files used by the collector to build the synchronization data sources in the remote iTop. Some of them must or may be adapted to meet customer's environment.

Next to the core parameters described here above, the collectors/params.distrib.xml file provides the list of all iTop classes that need to be discovered and, for each of them, lists the parameters that should be synchronized within iTop. Since the retrieval of InTune data is made in JSON format, this list must be aligned with the requirements expected by the standard JSON collector defined in the data collector base.

A difference must be made between the collector that looks after the Brand class and the others. As you'll see in the Usage section below, the Brand collector retrieves the whole list of managed devices from InTune and stores it locally in JSON format. All other collectors work from that file. This explains why the configuration file format differs between the Brand collector and the others.

Brand collector's configuration format is as follows:

  <itopbrandintunecollector>
                <ms_class>managedDevices</ms_class>
                <api_version>1.0</api_version>
                <jsonfile>data/InTuneManagedDevices.json</jsonfile>
                <path>value</path>
                <fields>
                        <primary_key>manufacturer</primary_key>
                        <name>manufacturer</name>
                </fields>
                <defaults/>
        </itopbrandintunecollector>

Next to the Brand collector, the collectors' configuration format for other classes is as follows:

  <itopNAME_OF_THE_CLASSintunecollector>
                <jsonfile>data/InTuneManagedDevices.json</jsonfile>
                <path>value</path>
                <fields>
                        <itop_attribute#1>graph_attribute#1</itop_attribute#1>
                        <itop_attribute#2>graph_attribute#2</itop_attribute#2>
                        ...
                        <itop_attribute_default#1>itop_attribute_default#1</itop_attribute_default#1>
                        ...
                        <itop_attribute#n>graph_attribute#n</itop_attribute#n>
                </fields>
                <defaults>
                        <itop_attribute_default#1>Default Value</itop_attribute_default#1>
                        ...
                </defaults>
                <nullified_attributes type="array">
                        <attribute>itop_attribute#n</attribute>
                </nullified_attributes>
        </itopNAME_OF_THE_CLASSintunecollector>

The Model collector's configuration is slightly different as it brings some precisions on the way InTune managed devices should be typed (as PCs, mobile phones…). For that purpose, it holds an additional section:

  <itopmodelintunecollector>
                ... same as for the general format
                <osfamily_type_default_mapping>
                        <OS_Family_#1>Type_#1</OS_Family_#1>
                        ...
                        <OS_Family_#n>Type_#n</OS_Family_#n>
                        ...
                        <OS_Family_#m type="array">
                                <brand>
                                        <name>Brand_name_#i</name>
                                        <type>Type_#i</type>
                                </brand>
                                <brand>
                                        <name>Brand_name_#j</name>
                                        <type>Type_#j</type>
                                </brand>
                                ...
                        </OS_Family_#m>
                </osfamily_type_default_mapping>
        </itopmodelintunecollector>

Here is an example of a default mapping for models:

  <osfamily_type_default_mapping>
                <Android>MobilePhone</Android>
                <iOS>MobilePhone</iOS>
                <iPadOS>Tablet</iPadOS>
                <Linux>PC</Linux>
                <macOS>PC</macOS>
                <Windows type="array">
                        <brand>
                                <name>Dell Inc.</name>
                                <type>PC</type>
                        </brand>
                        <brand>
                                <name>LENOVO</name>
                                <type>PC</type>
                        </brand>
                        <brand>
                                <name>Panasonic Connect Co., Ltd.</name>
                                <type>Tablet</type>
                        </brand>
                </Windows>
                <Chrome_OS>PC</Chrome_OS>
        </osfamily_type_default_mapping>

This section defines the list of classes that will be collected and in which order. It enables as well the possibility to deactivate the collection of a class.

<collectors_launch_sequence type="array">
        <!-- iTop Brands -->
        <collector>
                <name>iTopBrandInTuneCollector</name>
                <enable>yes</enable>
                <rank>1</rank>
        </collector>
        <!-- iTop Models -->
        <collector>
                <name>iTopModelInTuneCollector</name>
                <enable>yes</enable>
                <rank>2</rank>
        </collector>
        <!-- iTop OS Families -->
        <collector>
                <name>iTopOSFamilyInTuneCollector</name>
                <enable>yes</enable>
                <rank>3</rank>
        </collector>
        <!-- iTop OS Versions -->
        <collector>
                <name>iTopOSVersionInTuneCollector</name>
                <enable>yes</enable>
                <rank>4</rank>
        </collector>
        <!-- iTop Mobile Phones -->
        <collector>
                <name>iTopMobilePhoneInTuneCollector</name>
                <enable>yes</enable>
                <rank>5</rank>
        </collector>
        <!-- iTop PCs -->
        <collector>
                <name>iTopPCInTuneCollector</name>
                <enable>yes</enable>
                <rank>6</rank>
        </collector>
        <!-- iTop Tablets -->
        <collector>
                <name>iTopTabletInTuneCollector</name>
                <enable>yes</enable>
                <rank>7</rank>
        </collector>
</collectors_launch_sequence>

The launch of the InTune collector will be driven by the command and parameters defined in the usage section of iTop Data collector base. Once launched, first action of the collector will be to build its collection plan, based on the list of classes that have been enabled in the configuration file. Then,

• Configuration files will be consolidated,
• Synchronisation data sources will be created or updated if required,
• Authentication to InTune environment will be made (see below),
• Collection of InTune managed devices will be made through the iTopBrandInTune collector by invoking Graph REST API. Extracted data will be stored under the local “data” directory, in JSON format,
• Other collectors will not connect to InTune but will rely on the managed devices collected by the iTopBrandInTune collector to do their job, i.e. extract the data that are relevant to them,
• Synchronisation will run and InTune devices will be pushed to iTop.

This must be the first class to be collected. Defaults parameters for that class have been listed here above. During brand collection, all managed devices stored in InTune (limited to what the client ID set in the configuration file can see, of course) are gathered and stored in a JSON file, under the “data” directory of the collector. This file will, then, act as the source to extract the Brands and all other classes set in the class collection sequence.

It is during the collect of the Model class that typology will be brought to InTune devices by adding the correct type to a given Model of a given Brand. This is the reason why it is recommended to run it in second position. In order to achieve this, the collector will rely on the mapping that is provided in the configuration file, under the tag <osfamily_type_default_mapping>:

• For each of the OS families managed by InTune (listed here in Microsoft documentation), a default type may be given. For instance, iPadOS will be mapped to the class Tablet.
• If an OS family cannot be associated to a unique type (devices runing Windows may be PCs or Tablets in some organizations), a more detailed mapping can be created by giving a type to a brand. For instance, the brand Dell Inc. running a Windows OS will be mapped to the class PC.

With this mapping, device collectors (MobilePhone, PC, Tablet…) will be able to decide if a given managed device belongs to their class or not.

Mapping a type to an OS and / or a brand may quickly become a burden: the volume of mappings may be too large or a brand running a given OS may support too many different types of devices. This is where the Data model for Microsoft InTune will greatly help. Indeed, if the InTune collector detects that this extension has been installed on Itop, it will automatically import the unknown models with the type InTuneUnknown and the iTop Configuration manager will have the possibility, next, to set, though the iTop console, the proper type to the models that have flagged in iTop under this default type.

Models with an unknown type will appear as follow in iTop:

You may refer to the Model Management section of the Data model for Microsoft InTune documentation for further detail.

These are the next typology classes to be collected from InTune and synchronized wihtin iTop. It is recommended to run their collect in rank 3 and 4.

Their collect is driven by the configuration section specific to their collector:

• The iTop attributes are listed, together with their InTune counterpart,
• The default as well as the nullified attributes are specified.

A key action to be made during the collect is to give the right typology to managed devices. This is done through their Brand and Model which have been associated to a type in iTop. In the case where no type has been associated to the Brand and Model of a given managed device, then the device will not be synchronized within iTop.

Question: how does the authentication mechanism work ?
Answer: the collector relies on OAUTH2 authentication requested by Graph to retrieve data through its REST API. This is the exact same mechanism as the one implemented within the Data collector for Azure. Please, refer to the Q&A section of that collector for further details.

Question: how can I add InTune classes to the collection plan ?
Answer: Other classes than the ones listed by default in the collector can be added to its collection plan. For that purpose, we highly recommend to use the extensibility mechanism that is provided by the Data Collector base. You'll find the related documentation here.

Question: do I need to load the Data model for Microsoft InTune extension in my iTop for the collector to work ?
Answer: No. This is not a must. The Data collector for InTune has been built to handle both cases where the extension is installed and where it is not. However:

• If the extension has not been installed, only the following devices will be imported:
  • the ones which model already pre-exists in iTop,
  • the ones for which a mapping has been defined through the Model configuration.
• It it has been installed, the full flexibility provided by the collector to handle the managed devices' types, as described here above, will be available.