Bulk Modifications

There are two ways to perform bulk modifications in iTop:

Using the “Modify…” action on a list of objects: this is useful for data cleanup (normalization) when you want to align values within a set of objects, or for daily operations when you need to modify many objects in the same manner.
Using the Interactive CSV Import: this is useful for re-importing a set of exported and modified data.

The Modify Action

iTop allows the bulk modification of a list of objects. This operation is very useful for settings a field of many objects to the same value in one operation.

Bulk modification is possible only on a list if all the objects of the list are of the same class. For example it is not possible to perform a “Modify” on a list a Contacts, since the list may contain a mix of Teams and Persons. If you want to perform such an operation, make sure that you narrow your search to just one class of objects.
Not all users are allowed to perform bulk operations. If the menu item is not displayed in the drop-down list, ask your administrator to check the security profile of your iTop account.
Modifying a large number of objects (several hundreds or more) may require a lot of time to be performed. Since all interactive operations are time-limited for security reasons, contact your administrator before performing huge modifications to check if this is allowed/sustainable in interactive mode. An alternate solution for large update operations is to prepare a CSV file that will be loaded directly on the server in command-line mode.

Select “Modify…” from the “Other Actions” menu item, the following page is displayed:

At this step you can select the objects to be updated, by default all of them are checked and therefore will be modified. Browse the list to check that there is no issue and click on “Next »” to proceed to the next screen.

The object modification form appears with a checkbox and a numeric indicator next to each field. The indicator tells how many different values exist for this specific field among all the selected objects. If all objects have the same value for this field, the indicator is green (), the checkbox is checked and the field is editable. Otherwise, the indicator is red and the checkbox is unchecked. When the pointer of the mouse is positioned over a red indicator, a tooltip is displayed showing some information about the different values of the field.

Only the fields for which the corresponding checkbox is checked will be modified. All other fields will remain unchanged. By checking the checkbox in front of a “red” indicator (i.e. a field that contains several different values among the objects) you can force all the values to the same homogenous value.

Clicking on “Preview Modifications »” displays a confirmation screen:

Inspect the list to check if any error is reported in the “Operations” column, and when ready, click on “Modify All” to actually perform the bulk modification.

Interactive CSV Import

iTop provides a powerful CSV Import feature to assist end-users (and administrators) in massively creating or updating objects in iTop.

The CSV Import Wizard is launched by clicking the “CSV Import” menu in the “Data Administration” section.

Only users with “bulk modify” rights are allowed to use the interactive CSV import

CSV Templates

iTop provide CSV templates for creating/ importing any class of objects. You can either download or copy/paste the template from the third tab “Templates” of the CSV Import wizard.

Select the desired class from the drop-down list to generate the template. Then either click on the big Excel icon to download the template or copy/paste the text from the text area below the icon.

Another way to obtain a pre-filled template is to export existing objects in CSV. Refer to Export data for detailed instructions about how to perform this task.

Uploading Data

The first step of the CSV import consists in uploading the data on the server. You can either upload a file from your computer or directly copy/paste the data in the second tab of the wizard.

To upload the file from your computer, use the file upload form on the first tab of the wizard. Make sure that you also select the appropriate character set that was used for saving the file.

If the character set that you use is not available in the drop-down list, contact your iTop administrator (this list is configurable via the csv_import_charsets configuration variable).

If you choose to copy/paste the data, use the second tab “Copy and paste data” of the wizard:

Then click “Next »” to proceed with the next step of the wizard.

The following parameters must be adjusted during this step:

Parameter	Meaning
Separator Character	This is the character used for separating the different columns inside the CSV file. If the columns are properly displayed and separated in the preview at the bottom of the page, then the current choice is correct. (The typical choice for a CSV file is the comma)
Text Qualifier Character	Sometimes the values inside the cells contain the separator character. Such fields are then enclosed by the “text qualifier” character to prevent the separator character to be wrongly interpreted in the middle of a cell. (Typical value is either a simple or double quote)
Treat the first line as a header	Check this box if the first line of the file contains a header (column names) instead of actual data. Note that on the preview at the bottom of the page the header line is displayed with a different color.
Skip `x` lines at the beginning	Some CSV files (typically CSV files generated by hand made scripts) contain some comments at the beginning of the file. Use this setting to tell iTop to ignore as many lines as needed to skip the comments. The skipped lines are removed from the preview at the bottom of the page.

If the accented characters do not display properly in the preview, go back to the first page of the wizard using the “<< Back” button and pick the appropriate character set before uploading again your CSV file.

Once the data look correct in the preview, click on the “Next »” button to move to the next step:

The third step of the Import Wizard defines the mapping between the column of the CSV file and the fields of the object in iTop. The first operation consists in selecting the class of objects to import. This determines the list of fields available for the mapping.

Fields Mapping

If the CSV file has been originaly made of a template or an iTop CSV export, then the header provided in the CSV should give you the good mapping automatically.

If this is not the case you have to make this mapping manually.

The wizard requires a mapping for each column of the imported data. However a column can be ignored (i.e. not imported) by selecting “– ignore this field –” as the mapping for this column.

Search Keys

The CSV Import Wizard can be used to either create or update objects in iTop. The wizard uses the search criterias (the search “keys”) defined at this step to determine whether each line of the CSV file corresponds to an existing object in iTop or not. If the object exists, then it will be updated, otherwise it will be created. As usual in the search forms in iTop, all the selected search criterias are combined together using the AND operator. (i.e. an object must match all the value on the “keys” columns to be considered as a match).

The exact same imported CSV file can produce different results in iTop depending on the selected search keys. The number of objects created or updated depends on the search criterias configured at this stage.

Advanced Usage for Administrators

Administrators have access to an “Advanced mode” (checkbox at the top-right of the page), which allows to import objects based on their internal identifiers (ID or Key number). This is useful for renaming objects exported from iTop. Do not use this option for objects not exported from iTop, or at least make sure that you know the data you are importing!

Once the mapping and the search criterias look correct, proceed to the simulation of the import by clicking on the “Simulate Import” button.

After a few seconds, the following summary screen is displayed:

Note the number of objects to be created and the number of objects to be updated, as well as the number of errors. You can use the checkboxes at the top of the page to filter the display for a quicker analysis of the results.

The lines in errors are hilighted with a red background. Errors will not prevent the import from running, but the corresponding lines will be rejected.

If the simulation looks correct, click “Run the Import!” to perform the actual import. If you need to modify the data, click on “|<< Restart” (the Copy and paste data“ tab will contain a copy of the uploaded data).

If the number of objects imported and the percentage of objects to be created or updated exceeds a certain level, a confirmation dialog is displayed:

Click “Yes” to close the dialog and proceed with the data import.

The last screen of the wizard displays the summary of the operations performed during the import.

In case of errors, the rejected lines are listed at the bottom of the report, they can be copied/pasted and corrected before trying to import them again.

An alternative to this is to proceed iteratively:

Complete the import wizard, and note which lines have errors. Lines having errors are simply ignored.
Fix the lines in error within your reference CSV file.
Run again the import with your reference CSV file (the whole file)
Repeat until no error is found.

iTop will ignore lines that have been unchanged, because the corresponding data is already up to date (unless modified by somebody else in the mean time between two imports). Iterating on the whole CSV file may be the preferred option if you need to maintain a reference CSV file of your data.

Sidebar