File Import - Issue Data

The file import utility allows the administrator to upload a tab-delimited or comma-delimited file from their client computer, for the fields and values within this file to be mapped to ExtraView values, to validate the data and to finally import the data. Data can be uploaded as new issues, or can be used to update existing issues. Access to this feature is via the security permission key named CF_FILE_IMPORT. The import works as a separate process for each business area and project, therefore your import files will only target a single business area and project. For a record to be imported and inserted as new, it must exist on the appropriate add layout or one of its embedded layouts for the business area and project. For a record to be imported and update an existing record, it must exist on the appropriate edit layout or one of its embedded layouts for the business area and project.

Note: The Add / Update task must be configured and running for the file import utility to work.  This is because the performance is optimized when the utility is running in the background.  Further, this allows multiple copies of the utility to run at one time, further increasing the performance of the import.

Typically, the files to be imported will contain data from other systems that is to be inserted into ExtraView. Microsoft Excel is a good tool that can be used to prepare data in the appropriate format for the import. The process followed is:

  • Create a template for the import and upload the file
  • ExtraView automatically provides mappings for fields that are both in the uploaded file and within the ExtraView database
  • ExtraView automatically provides mappings for field values that are both in the uploaded file and within the ExtraView database
  • You can see the results of the mapping and alter the mapping of any field or field value
  • You may then validate the uploaded data, ensuring the file is error free before performing the upload
  • On the validation screen, there is an alternative to download the file that was uploaded. This is in addition to being able to observe the errors on the screen. If there were errors in the uploaded data found by the validation process, these errors will be shown within the file you can download. This simplifies the process of finding, fixing, re-uploading and re-validating the data before you perform the import
  • Finally, you can perform the import and insert the records.

Note: ExtraView will ignore whether fields are or are not mandatory when importing data. It will also ignore whether fields have correct allowed value relationships when importing data. It will not ignore read-only fields and later in this section, you will find how to import fields that are read-only on your edit screen layout. However, when you edit any of these records in the web-interface or via the CLI, and attempt to update, the appropriate validations will be performed and you must correct any errors of these types at this time. Fields with default values defined in the data dictionary will have the default value created, unless there is a value provided in the import file.

Import Templates

When you use the File Import Utility, you create a template that may be reused as many times as needed. This aids the sometimes repetitive process of validating and correcting your data. You can set up the field and value mappings once, and upload your import file as often as is required, validating the data as you progress. This also aids the routine uploading and importing of data from other sources, as the same mappings can be used each time, without the need to set these up.

There are three import modes from which to select, when you create the import template:

  1. Insert Issues - New issues are created from each record in the import file.
  2. Update Issues - Existing issues are updated from each record in the import file. There must be an ID column within the import file, and this must contain the ID of the issue to be updated
  3. Update and Insert Issues - New issues may be created and existing records may be updated. To facilitate this, there must be an ID column within the import file, and this must contain the ID of issues to be updated. If the field is left blank, then the record will be inserted. Note that the corresponding add layout for the business area and project is used for validation purposes, when inserting issues, and the edit layout is used when updating issues

Large Volume Imports

Special consideration may be made when you have tens of thousands or more records that must be imported in a short space of time.  You may configure multiple import files and these can be imported in parallel.  Please see the section on large volume imports for more information.