This article walks the user through the steps of importing a file using the Data Import Tool (DIT).
For a high level walkthrough of the Data Import Tool, including settings and descriptions of the various screens, please review the Introduction to Using the Data Import Tool article.
Performing an Import
The Clarity Data Import Tool (DIT) will accept data in the 6.1 version of HMIS CSV or XML. For further documentation on specifications for each of these formats, please reference the HMIS Data Exchange Resources website.
If using the HMIS XML data format during imports, the DIT allows for the XML schema to be expanded to include custom fields outside of the standard HMIS XML schema. When custom fields are published within Clarity, the stored XML schema is expanded with those custom fields ensuring a successful validation prior to import.
For more information on custom fields, please review the Custom Fields section of the Introduction to Using the Data Import Tool Help Center article.
Accessing the Data Import Tool
To access the Data Import Tool (DIT), your Clarity user account must be assigned a role that has been configured to allow access. To use the DIT for importing data, click the Launchpad icon and select Data Import.
Adding a File to the Upload Queue
Files can be uploaded on the Home screen of the DIT interface. This can be done using two methods described below.
Drag and Drop
The Drag and Drop method of uploading files allows the user to physically click on a file entity and drag it onto the DIT screen. The user can drag and drop a single file, a ZIP file containing one or more files, or an entire folder containing one or more files.
Clicking the Select File button will open the file explorer window for your OS and will allow you to select a single file or a ZIP file containing one or more files.
Note: When uploading a compressed ZIP file, the importer is expecting the ZIP to only contain CSV or XML files. Any extraneous files, folders, or subfolders will cause an error suggesting to review the file structure within the compressed file before attempting another upload.
Uploading a File
Once a file has been added to the DIT queue, the filename and file size will be displayed in the user interface. Several files can be added to the DIT if needed. From here the user can click the Upload File button to upload the file for validation or click the Cancel button to remove the file from the queue.
Once the file has been uploaded from the queue, the validation process allows the DIT to read the contents of the file and performs checks to ensure the file is ready to be validated for adherence the data formatting specifications. To begin the validation process, click the Start Validation button.
Once validation has taken place, the screen will display a number of sections that include analysis information on the contents of the file as well as an area to map program and service data.
A Data Analysis section provides a display of counts for the different types of records within the source data files to be imported. There is also a Program and Service Mapping area displaying an unduplicated count of each. These sections allow the user to map source file records to existing records within Clarity.
Mapping Programs and Services
The Data Import Tool provides users the ability to map source records from the file being imported to existing destination records within the Clarity system for Programs and Services. Establishing this relationship is key to ensuring data quality. Please note that if programs and/or services are not mapped here, the associated records will not be included in the import process.
The Program Mapping section gives the user the ability to map programs in the source file to existing programs within Clarity.
To begin this process, you must first establish the agency you wish to import data into using the Select Organization dropdown. Once the agency is selected, the dropdowns respective to each source program in the file is populated with existing programs within Clarity.
Click the Save button once each source program has been configured to associate with a Clarity program.
Similar to Program Mapping, the Service Mapping section allows for service types from the source file to be mapped to existing service items in Clarity.
First, use the Select Project and Select Organization dropdowns to narrow down the Clarity service items available to each service item in the source file to be mapped to.
Next, use the dropdowns adjacent to the source service types to select the service type to map to within the Clarity system.
Once the service types have been selected for each source type, click the Save button.
Importing the File(s)
Once Program and Services mapping has been completed, the data can be imported into the Clarity system.
To begin the import process, click the Import icon for the file instance at the top of the screen.
The screen will refresh showing the import progress and number of files being processed. Click Cancel to abort the import process at any time.
When the import completes, the file instance at the top of the screen will indicate Imported.
Viewing the Import Results
Click the Show Results button at the bottom of the screen to see how the data was imported into the Clarity system.
The Message column of the list of results inform the user how the data import tool handled that specific record. If an error has occurred, details on the error will be displayed giving the user an opportunity to resolve those errors on a subsequent import attempt.