Bulk Import of Configuration Items
The Components of a Bulk Import API Request
The Bulk API is based on REST principles and is optimized for working with large sets of data. Bulk import is performed by initiating an import job and then monitor if the job was successfully executed. When several types of records that have dependencies (for example a people record can only be imported when the organization to which the person belongs already exists) need to be imported, you need to check if the first import was successfully executed before you can launch the second import (these import jobs are executed asynchronously).
A Bulk API request consist of 4 components: the url (the endpoint), the HTTP Verb (the method), the headers and the parameters.
The Bulk Import API Endpoints
These are the endpoints of the Bulk Import API:
- Production enviroment:
- QA environment:
- Demo environment:
The Bulk API Verbs
To initiate a Bulk Import API you need to perform a POST Request. Polling the import progress is done with a GET Request.
The HTTP Headers
Each request to the 4me REST API must supply two headers to specify your personal access token and to specify the 4me account you need access to:
Authorization: Bearer <personal-access-token>
When you initiate an import you need to define 2 parameters: type and file.
In Curl you can define these parameters with the -F option:
Provisioning of Configuration Items
In the following exercise you will emulate what the integration with a discovery tool should do: load products and configuration items in 4me.
For this exercise we have prepared three import files:
- Products: it_bulk_import_products.csv
- Configuration Items: it_bulk_import_cis.csv
- Configuration Item Relations: it_bulk_import_ci_relations.csv
In this scenario 2 new laptops – of model Microsoft Surface Laptop 3 – and a new software – Microsoft Visual Studio Enterprise 2021 – were discovered. The product import file contains the hardware product and the software product for these new configuration items. In the CI relations file the discovery tool tells us that on each of the laptops that have been discovered Microsoft Office Professional 2019 version 1809 and Microsoft Visual Studio Enterprise 2021 have been installed and that Microsoft Visual Studio Enterprise 2021 has also been installed on the PC with label CMP00027.
Can you manually execute the Bulk Import API calls a discovery integration needs to perform to import the above files in the 4me Widget Data Center (id = wdc) account? Don’t forget to define the right scope for the personal access token!
Copy the products import file to a folder on your hard drive (for example
/tmp/it_bulk_import_products.csv) and upload the file with:
curl -X POST -i -H "Authorization: Bearer <personal-token>" -H "X-4me-Account: wdc" -F type=products -F "file=@/tmp/it_bulk_import_products.csv" "https://api.4me-demo.com/v1/import"
Next poll the status of the import (make sure the products import has finished before you execute the next import) using the token (something like ‘68ef5ef0…db41e68’) received after the previous call:
curl -X GET -i -H "Authorization: Bearer <personal-token>" -H "X-4me-Account: wdc" "https://api.4me-demo.com/v1/import/68ef5ef0...db41e68"
Check if the import of the producs was successful: you should find the 2 new product now in the specialist user interface. Then copy the configuration items to
/tmp/it_bulk_import_cis.csv and upload the file with:
curl -X POST -i -H "Authorization: Bearer <personal-token>" -H "X-4me-Account: wdc" -F type=cis -F "file=@/tmp/it_bulk_import_cis.csv" "https://api.4me-demo.com/v1/import"
Check if the import of the configuration items was successful: you should find the 3 new configuration items in the specialist user interface. Then copy the configuration item relations to
/tmp/it_bulk_import_ci_relations.csv and upload the file with:
curl -X POST -i -H "Authorization: Bearer <personal-token>" -H "X-4me-Account: wdc" -F type=ci_relations -F "file=@/tmp/it_bulk_import_ci_relations.csv" "https://api.4me-demo.com/v1/import"
Check the contents of the CI relations import file
it_bulk_import_ci_relations.csv. To identify the hardware items two different techniques have been used: by
Source/SourceID and by
The new software Microsoft Visual Studio Enterprise 2021 was added to the laptop with label CMP00027. This CI was already related to other software CIs. What happened with these relations?
The relations with the other software CIs have been kept because they were manually created and have no
Source defined. These relations would have been removed if they had the same
Source as the one in the import file. This allows a discovery tool to remove obsolete relations by just importing the actual relations that have been discovered (but without modifying relations that are manually managed or managed by another discovery system).