Discovery Tools
A common use of the Import API is to build an integration with one or more discovery tools. Tools like Microsoft System Center Configuration Manager (SCCM) or HP Network Node Manager (NNM) can discover hard- and software items within a network. Such tools are typically also able to discover some relations between the discovered items. This information can be used to automatically add and update Products, Configuration Items and relations between Configuration Items in R-Service.
As an alternative to using the Import API we also offer the discoveredConfigurationItems mutation in our GraphQL API. The advantage of that API is that the information of a set of Configuration Items (and their Product Categories, Products and relations) can be sent in a single call.
Integrating With Discovery Tools
Multiple discovery tools can be integrated with R-Service. To ensure that R-Service is able to distinguish between different discovery tools, a unique identifier should be chosen for each discovery tool. The identifier of a discovery tool can then be stored in the Source field of the R-Service records that are generated and maintained by this tool. Examples of such identifiers could be SCCM or NNM. Longer names with spaces (up to a maximum of 30 characters) may also be used to populate the Source field of a record.
Furthermore each Configuration Item and Product should be assigned a unique Source ID to identify it independent of the identifier assigned by R-Service. The usage of Source and Source ID is important for both the Import and the GraphQL API.
Using GraphQL
We believe using GraphQL is an easier alternative to using import files. To upload information from discovery tools one can use the discoveredConfigurationItems mutation. The advantage of that API is that the information of a set of Configuration Items (and their Product Categories, Products and relations) can be sent in a single call. The mutation will provide an immediate response containing an AsyncQuery which can be used to retrieve the results of the processing of all information sent.
The intended usage is that all discovered Configuration Items are sent in batches (of 100 items). The resultUrls, of the AsyncQueries returned, can then be polled to retrieve the (JSON) results of processing each batch.
Just as with the Import API usage of the Source and Source ID values is essential to properly identify items without relying on identifiers generated by R-Service.
When uploading discovered items this way one must supply Product Category and Product information. This allows new records to be created without having to check for their existence first and possibly having to create them separately. Product Categories are not identified by their Source ID (although that may be supplied) but instead by their reference which is the immutable identifier automatically assigned to each category, based on its name, on creation. Using the DiscoveredItemStrategy you can indicate whether the supplied fields should overwrite existing Product (Category) information in R-Service, or should only be used to create new records if they are not yet know.
Besides matching Configuration Items based on their assigned Source and Source ID this API will also attempt to match Configuration Items based on their serial number on initial upload. This means that discovered items are matched to items already present in R-Service on first upload (i.e. when no record is found in R-Service based on their Source ID). So if a Configuration Item with the supplied serial number is entered manually before it is discovered (and uploaded) the uploaded information is used to update the manually entered item instead of creating a new one. The Source ID value uploaded is also assigned to the manually entered item so future updates will be applied to the right record.
Products are handled similarly to Configuration Items, only using Product ID instead of serial number. So besides looking up Products based on their assigned Source and Source ID this API will also attempt to match them based on their product identifier on initial upload. This means that discovered products are matched to products already present in R-Service on first upload (i.e. when no record is found in R-Service based on their Source ID). So if a Product with the supplied productID is entered manually before any Configuration Items based on it are discovered (and uploaded) the uploaded Configuration Items will be linked to that Product instead of creating a new one. The Source ID value uploaded is also assigned to the manually entered product so future uploads will also be linked to the right record.
Using the Import API
Besides using GraphQL one can also use the Import API to upload information from discovery tools using files. Using this approach one must assure a matching Product record exists (that describes the Configuration Item’s hardware model or software application) before a new Configuration Item record can be registered.
It is important to fill out the Source column for each row when an import file is prepared using data from a discovery tool. In addition, for a Configuration Items import file, the Source ID column should be set for each Configuration Item to the unique identifier by which the Configuration Item is known within the discovery tool. Having both the Source and Source ID values stored in R-Service makes it possible for a discovery tool to update a Configuration Item record without knowing its ID (see Create or update).
Below an example is provided of how the Source and Source ID columns of a Products import file could be filled out using data from a discovery tool. Such a Products import file should be imported before Configuration Items are imported to ensure that all the necessary Products are available in R-Service.
Source Source ID Name Brand Model Category
SCCM Abobe Reader Abobe Reader Adobe software/browser_viewer_application
SCCM Microsoft Windows 7 Microsoft Windows 7 Microsoft software/operating_system_software
SCCM VMware ESXi VMware ESXi VMware software/operating_system_software
SCCM Dell Precision M4400 Dell Precision M4400 Laptop PC Dell Precision M4400 computer/laptop_pc
SCCM IBM Power 795 IBM Power 795 Server IBM Power 795 computer/server
After the Products have been imported, the CSV or TSV file with the Configuration Item information can be imported. Before starting the Configuration Items import, however, use the polling feature to make sure that the Products import has completed and that it was successful.
The example below demonstrates how the Source and Source ID fields can be used in a Configuration Items import file to ensure that Configuration Items can be identified uniquely using data only from the discovery tool.
Source Source ID Product Label Name System ID
SCCM AbobeReader9.1.0 Adobe Reader Abobe Reader 9.1.0
SCCM MicrosoftWindows7ProSP3 Microsoft Windows 7 Microsoft Windows 7 Pro SP3
SCCM VMwareESXiBuild164009 VMware ESXi VMware ESXi 4.0 Build 164009
SCCM 01:23:45:67:89:ab Dell Precision M4400 Laptop PC CMP00052 Dell Precision M4400 Laptop PC http://sccm.example.com?mac=0123456789ab
SCCM 5691602 IBM Power 795 CMP00207 IBM Power 795 Server http://sccm.example.com?id=5691602
Note that the names without spaces were used to define a Source ID for the software Configuration Items. This was done to demonstrate how the length of the text string in the Source ID field, which can contain a maximum of 128 characters, can be reduced.
The example URLs for the System ID field are hypothetical. The importance of specifying a hyperlink in the System ID field is explained in the blog post Afraid of the CMDB?
Once the Configuration Items have been imported, the Configuration Item relations can be imported. Again, use the polling feature to make sure that the Configuration Items import has completed and that it was successful.
Below is an example of a Configuration Items Relations import file that relates an operating system and an application to a personal computer that is identified by its MAC address.
Source CI Source CI Source ID Related CI Source Related CI Source ID Relation Type
SCCM SCCM 01:23:45:67:89:ab SCCM AbobeReader9.1.0 child
SCCM SCCM 01:23:45:67:89:ab SCCM MicrosoftWindows7ProSP3 child
If one or more relations are defined for a Configuration Item in the import file and a Source is specified in the first column for these relations, then all existing relations of that CI with the same Source will be removed during the import.
Important: Make sure all relations for a Configuration Item are grouped together in the import file. Otherwise the last relation that is specified for a Configuration Item in the import file will cause the previous relations, which were added during the import for that same Configuration Item, to be removed.
If the Source is not defined for a relation in the import file, then the relation will be added during the import without removing any existing relations.