Bulk Import of Configuration Items
Integrations Bulk API Training Bulk API

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:

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:

  1. Authorization: Bearer <personal-access-token>
  2. X-4me-Account: <accountID>

The Parameters

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:
-F "type=organizations"
-F "file=@temp/organizations.csv"

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.

Please read the documentation on the 4me Developer Site carefully to get a good understanding of how the integration with discovery tools has to be done.

For this exercise we have prepared three import files:

  1. Products: it_bulk_import_products.csv
  2. Configuration Items: it_bulk_import_cis.csv
  3. 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.


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 label.

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).

Next Topic