This article contains answers to some of the most frequently asked questions Bitfocus receives about our Data Import Tool (DIT).
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 have actual data in them, other than the header rows.
- Export.csv: include the standard Export.csv record in this file.
Q: How can I generate a sample CSV or XML file?
A: You can run an export 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 how the processor is set up in Clarity Human Services in order 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 if the user intended to change a non-null value to a null value or not.
Q: How do service mappings occur?
A: Service mappings operate in a similar way as other data elements, where you have an external ID that needs to be mapped to a Clarity Human Services ID. However, there are extra details to keep in mind with how this information is stored. Because of the way services are structured in the XML/CSV, it takes some extra processing to determine what that specific external ID will be.
Usually, Bitfocus generates that external ID for you, as a combination of ProjectID (from the enrollment), RecordType, TypeProvided, SubTypeProvided, and ReferralOutcome. This creates a string that can't be predicted, which works fine when using the DIT UI all the time. You can select mappings from the dropdown menus and move on. But if you're trying to send files programmatically and not through the DIT UI, there is no way of knowing how to create the mappings because you don't know what the generated strings will be.
To alleviate this, we allow you to add an extra tag in the ServiceFAReferral element. It’s the hmis:ServiceItemID tag, which allows you to put in your own ID for that service. Then you can create a mapping to what that external ID should correspond to in Clarity Human Services. See below:
In this case, the legacy ID of 123 was added to the ServiceFAReferral element. The DIT will see that and it will not try to focus on the RecordType, TypeProvided, etc. It will just try to find a mapping that’s been saved for the same Source ID this file is associated with that points 123 to a Clarity Human Service Item ID. If you are using the API to import data, you need to also upload a Mapping XML file that indicates the Clarity Human Service Item ID that 123 should be associated with (see the Clarity Human Services Mapping Document section of Importing Data Using the XML API Tool).
Q: How can I import custom fields?
A: Custom fields are imported via XML only. There is no mechanism to import custom fields in CSV format. For more information, see Importing Data Using the Data Import Tool (DIT).
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 XML as an ‘x’ (lower-case x). No other characters are allowed as placeholders, and will be flagged as invalid during validation. DIT CSV validation will warn and convert disallowed characters to ‘x’s on import, and the DIT XML will mark the validation as failed and entirely block the import until the placeholder characters are changed to ‘x’s and the XML validated again.
Refer to our Data Import Tool (DIT) Sample Files article for sample files covering common import scenarios.
Updated: 07/23/2024