Best Practices for Importing Data

Resolving Import Problems

Inspect imported data after each process finishes. If data was not imported as you expected, modify your spreadsheet and import data again. Be sure to:

Review mapping guidelines specified in Field Mapping Considerations.
Modify spreadsheet columns and rows based on these guidelines.
Include a column that can be used to detect duplicate items in your system.
Select the Replace mapped attributes option on the Import Options page.
Map fields as needed.
Perform the import.
Inspect imported data.

Note: On-premise customers should consider backing up the SBM Application Engine database before beginning a data import.

Generating Item IDs

If you are importing new issues into a project, take advantage of SBM's automatic Item ID assignment. If you do not map to the SBM Item ID field, the system will generate Item IDs based on numbering properties for the project you are importing into.

For best results, include a column in the spreadsheet for item types (Requests, for example) and map this column to the system Item Type field. Each spreadsheet row can contain either the Item Type value, such as Request, or a prefix, such as REQ. SBM will match spreadsheet values to Item Type prefixes and values specified in SBM Composer.

Mapping Users and Groups to Imported Data

If your spreadsheet contains columns that will be mapped to User or Group fields, verify that imported data corresponds to existing login IDs, user, or group names. For example, if data in a row is not matched to user accounts, the row is skipped. New users are not created.

If accounts do not exist for imported items, use the Import Users feature to import users before you import associated data. This enables you to import users as a copy of an existing user, which saves manual configuration later.

For Multi- fields that support group and user names, if you are importing a value that happens to be both a user name and a group name, the import process considers the user name as primary—the import will attempt to match the value to a user name first, and then attempt to match a group name if a user name is not found. If neither match is found, the record is skipped.

Handling Selection Field Values

Values for selection fields, such as Single/Multi-Selection, Single/Multi-Relational, and User/Multi-User fields, must exist in your system before you can import items that include these values. Spreadsheet rows that contain invalid values for these field types are skipped.

Use the Replace data in Multi- type fields option if you want to overwrite Multi-User, Multi-Group, Multi-Selection, and Multi-Relational fields instead of adding new selections to those field types.

To prevent errors on import, review the guidelines in Field Mapping Considerations and verify that existing values are available before you import data.

Handling Required Fields

You do not need to provide data for required fields in order to import them, but users will need to provide valid values for required fields before they can work with imported items.

If you choose not to import values for required fields during the import process, verify that required fields are visible to users who might update or transition imported items, and that they have permissions to modify required fields.

Setting (None) Values

You can set Multi-Group, auxiliary Multi-Relational, Multi-Selection, auxiliary Single Relational, Single Selection, and User fields to have "None" values after import. This can be useful if you are re-importing data and want to clear previously imported values for fields.

To do so, clear data from spreadsheet rows mapped to applicable fields before the import and be sure to clear the Set default values for empty cells check box in the Field Mapping area.

Importing Contacts

For best results, use the Import User feature to establish items in the system Contacts table. This ensures that spreadsheet data is correctly mapped to Contacts fields. For details, refer to Spreadsheet Import Options and Mapping Attributes to SBM Fields.

After you establish Contacts records through the Import User feature, you can use the Import Data feature to update additional data for Contacts records as needed.

Importing Data into Relational Fields

You can import data into Relational fields that reference a primary or auxiliary table:

When you perform an import using a Relational field that points to a primary table, you must include either the Item Id or the Title field value for the related items in your spreadsheet.

When you map to a Relational field and perform an import, a search for existing items by Item Id is performed first, followed by a search by Title if needed. For example, if a unique Item Id is not found (or more than one is found) the system cannot tell which primary item to insert into the Relational field; therefore, a search by Title is used instead. In this case, you must ensure that the Title field value is unique.

Note that the Item Id in your source spreadsheet should contain a prefix if the target primary table items contain a prefix. For example, DEF287954 will be found in the Issues table, but 287954 will not. This is done to prevent duplication.
When you perform an import using a Relational field that points to an auxiliary table, you must use a Title field value for the related items in your spreadsheet.

When you perform an import into a Multi-Relational field, use the Parse multiple values in a cell option to split the cell value into multiple values using the value separator of your choice.