Prepare Import Files
Introduction
The Bulk API for Imports makes it possible to create or update multiple records in batches.
The Import API is most commonly used to build provisioning integrations:
- for products and configuration items with Discovery Tools,
- for people, organizations and sites with Directory Services,
- for custom collection elements like cost centers with ERP systems like SAP or Microsoft Dynamics.
The functionally is similar to the Import feature that is available to account administrators within the 4me user interface.
The Format of an Import File
Imports into 4me are done based on UTF-8 encoded comma-separated values (CSV) files. The format of the import files can be found on the 4me developer site on this page.
Each record in a CSV file needs to be defined on a separate line with the the first line of text reserved for the column headers.
Each column header references a field of the record type. Not all column headers are required. If a column for a field is left out of an import file, it will cause the corresponding field to be set to its default value (usually this means that it is left empty) when the import causes new records to be generated. For existing records a missing column means that the corresponding field value will not be updated during the import.
During the exercises of this training you will use some example import files. Download the following it_bulk_import_products.csv file that contains some product records. Open the csv file you have downloaded with one of the tools we have recommended (see here).
Questions:
Check the values in the columns Source and Source ID. What are these fields used for ?
The Source identifies the discovery system that is considered as the master of the data. In this example this is LanSweeper. The Source ID is the unique identifier of the given product in the discovery system. In this example the product ID is used.
Why is the ID column empty? What will happen during the import when values are defined for the ID?
The ID is the unique identifier of the record in 4me. For discovery integrations this column should be empty: when creating new records the ID is not known yet. When an update is required of an existing record your discovery system will not know the corresponding 4me ID: so it will use the Source and Source ID to identify the 4me record to be updated.
Check the values in the column Financial Owner. Knowing that this import file will be used to import products in the Widget Data Center (id = wdc) account, what is the meaning of the ’ @ widget’ value at the end of the organization ‘Widget Data Center, Internal IT’ that is specified as financial owner?
The organization ‘Widget Data Center, Internal IT’ is not defined in the ‘Widget Data Center’ account but in the directory account ‘Widget International’ (id = widget). With the ’ @account-id)’ suffix you can specify in which account a related record can be found.
Enumerations
Some fields like the Status field require specific predefined values to be selected from a fixed list of options. These fixed lists of options are called enumerations. You can check the list with enumerations here. Your integration should use the Enumerations API to get these values.
In the next step you will use the 4me Bulk API to import files in the demo environment.