Form Importing was introduced in CaseLocker v0.7.00.
Form Imports prior to 0.7.00, which only supported creating empty forms, have been deprecated. For historical purposes, this import history is accessible by selecting "View Legacy Imports" on the Form Importing page.
The Form Import CSV File
All Form Imports must use an import file generated by CaseLocker. These import files can be downloaded from the Form Template, and in the Import Dialog. Headers in the import CSVs should not be modified, as modification can cause your data to fail to import.
Headers in the import file are formatted "{Question ID}-{FieldType ID}-(List Row ID)", with List Row ID used to indicate the row in a list question beginning at 1.
For List questions, the import file will at minimum contain one of these columns (with the List Row ID being 1). If the question has minimum rows and/or maximum rows set, the import file will contain up to the minimum/maximum rows.
There are two types of import files, a create forms file and an update forms file. The only difference between these import files is whether a case number is required, or a form ID.
Create Forms
This import file contains the required headers to import new forms onto a contact. The case number (new in v0.8.04) is required to know the contact to add the form to.
Update Forms
This import file contains the required headers to update existing forms. The form ID is required to know the form to modify the data for.
Import a File
To start an import, select "New Import" in the Form Import page.
In the dialog that appears, enter the name of the template you wish to import data for. Once a template is selected, more options will appear, allowing you to select the file to upload, settings for the import, and buttons to quickly download the Create and Update CSVs.
The following options are available in the import dialog:
- Import File - Required - The file to import data from
- Operation Type - Required - Whether the import is to create new forms or to update existing forms.
- Add Additional Tags - Optional - Add one or more tags to the forms, in addition to any tags included in the Tags column in the import file.
- Set Status - Required on Creation, Optional on Update - The status to set the forms to.
The following options are available after checking "Advanced Options":
- Clear Form - Optional - Delete all existing data in the form prior to import.
This action is DESTRUCTIVE, and can result in the loss of data if used improperly. A warning will appear after selecting Run Task to confirm you understand the risks.
Importing only modifies data that is contained in the Import File. Empty columns will not delete or clear any existing values in the Form. Setting the Clear Form option will delete existing answers prior to importing data.
Import Limitations
The File fieldtype cannot be imported at this time. These questions will not appear on import files.
Validation & Errors
Once you select "Run Task", the import file will be validated. Column headers will be validated, and each row will be validated to ensure that answers match the any required formatting or options. The following fieldtypes may cause validation errors:
- Dropdown, Radio - The answer must be empty, or only one valid option.
- Checkbox - The answer must be empty, or one or more valid option separated by semicolons.
- Regular Expression - The answer must match the expected validation pattern.
- Date - The answer must be a year (YYYY), month/year (MM/YYYY), or month/day/year (MM/DD/YYYY).
- Social Security Number - The answer must match IRS published rules for Social Security Numbers. These fields must be in the format ###-##-####, and must be a whole SSN (prepending the last four with zeros will fail).
- Email - The answer must match a "username@mail.com" format.
- Numbers, Currency - Answers must only contain a number.
If a validation error occurs, the progress and status will indicate "Failed". You can view the rows that failed validation by selecting "Download Errors" and looking in the last column "Errors". Each error for a row will be placed in this column, with the reason for the validation failure.
If validation passes, but there are errors after importing, the progress bar will indicate "Finished with Errors". You can click on the progress bar to view a list of all errors, including the row in the import file that they occurred on.
Errors that can occur include:
- The current status (Complete, Submitted, Not Completing, and any Signing Status) is preventing data from being imported.
- An unsupported character exists in the import file. CaseLocker supports the UTF8 character set, however you may need to save the import file as CSV UTF8 in order to support these characters.
If Importing completes without an error, the progress and status will indicate "Finished".
Viewing Modified Forms and Import Logging
After an import, you can select "View Forms" on the import task to view all forms that were created or updated by that job.
An event log is created in each form that is created or updated, displaying the job type and the user that imported the data. You can view these events by selecting "Activity Log" in the form.