Data Import Tool (DIT) Frequently Asked Questions (FAQ)

Overview

This article answers common questions about importing data with the Data Import Tool (DIT), including requirements for HUD HMIS CSV and Clarity CSV files, service mapping, custom fields, and validation.

Q: What is the minimum amount of data in an HMIS CSV dataset to import only client records and no other data?

A: The following files are required in order to import client records and no other data using the DIT:

• Client.csv: include the client record(s), as usual, in this file.
• Enrollment.csv, Exit.csv, and Project.csv: these files must exist, but can contain only the standard headers. They do not need to contain any data other than the header rows.
• Export.csv: include the standard Export.csv record in this file.

Q: How can I generate a sample CSV file?

A: You can run the [HUDX-111(-AD)] HUD CSV Export [FY 2026] report on your site.

Q: Are AssessmentResults imported through the DIT?

A: No, the DIT doesn’t look at AssessmentResults data. It relies on the AssessmentQuestions data and on how the processor is set up in Clarity Human Services to score the assessments it imports.

Q: Will the DIT overwrite records that have "good" data with null data?

A: Yes. The DIT uses the record's DateUpdated fields to determine which data is newer. It does not know whether the user intended to change a non-null value to null.

Q: How do service mappings occur?

A: Service mappings work like other data elements. Each service in your file has an external ID that must be mapped to a Clarity Human Services service.

Bitfocus generates the external ID from a combination of ProjectID (from the enrollment), RecordType, TypeProvided, SubTypeProvided, and ReferralOutcome. Because these strings can't be predicted, services are mapped in the DIT UI. In the Service Mapping section, select the Clarity Human Services service for each source service from the dropdown, and then save the mapping.

Review your mappings after any changes to the program or service catalog.

Q: How can I import custom fields?

A: Custom fields are imported using Clarity CSV. They are carried as additional columns appended after ExportID in these files:

• ClarityClient.csv (Client Profile custom fields)
• ClarityEnrollment.csv (enrollment, exit, status update, and annual assessment custom fields)
• ClarityAssessment.csv (assessment custom fields)

Custom fields are not available in the service, expense, or attendance files. Column order must match your instance's field schema exactly. The standard HUD HMIS CSV does not carry Clarity custom fields. For more information, see Importing Data Using the Data Import Tool (DIT).

Q: How can I import multi-select fields?

A: To import to a multi-select field, use the values from the multi-select selection options, separate each value by a comma, and enclose in brackets.

For example, the values in your file should look something like this: [1,2,3]  

This is the correct format for CSV files.

Q: Why aren't my mapping options coming up when I try to import a file?

A: A key part of mapping projects and services is the export.sourceID field. This is used to differentiate one source system from another. Please check that the field is not empty, and it matches any previous imports from that system.

Q: Does the DIT allow placeholder characters for missing Social Security Number values?

A: Yes. Missing Social Security Number values can be represented in the HMIS CSV and Clarity CSV as a lower-case "x". No other characters are allowed as placeholders. DIT CSV validation will warn and convert disallowed characters to "x" on import.

Q: Does the DIT still accept Clarity XML?

A: No. Clarity XML, including Clarity XML 2026 and Clarity XML (Mapping), was retired on September 30, 2026. The DIT accepts HUD HMIS CSV and Clarity CSV. See Migrating from Clarity XML to Clarity CSV.

Refer to our Data Import Tool (DIT) Sample Files article for sample files covering common import scenarios.

Updated: 10/01/2026