Importing Data Into an Existing Form

This article covers how to import data into an existing form. You must be at least an Administrator to use the import feature. 

Overview

If you have been collecting data from another source and would like to migrate this data into your Zengine workspace, you have the capability to import this data.  Several steps must be taken in order to ensure that the data is formatted properly and that it matches the structure of the existing data in your workspace.

Preparing Your File for Import

BEFORE YOU START! Please be aware that there is a limit to the number of rows you can import at one time (2000 records). Check out our Limits Article to learn more.

The format of the file to be imported is important and the data in the columns and rows must be consistent.  Before importing your data, read these guidelines below to make sure your data will import successfully.  

1. Header Row: The first row of your spreadsheet should contain the names for every column. 
2. Column Names: If the names of your columns match the names of fields in your workspace exactly, it will be easier to map your columns to the form fields when importing. Therefore, it is in your best interest to name the columns as the fields are named. (Note that automatic mapping is case sensitive. In other words, if your field is called "email" and your column is "Email" the system will not automatically map them, but "email" will auto-map to "email.")
3. Mapping columns to fields: Please ensure that you have only one column for each field on your form and no duplicate columns. A column in your file to be imported can only be imported into one field.
4. Order of columns: It is easiest when you order the columns in the same order as they appear on your form, although that is not necessary. 
5. Consistent columns: Make sure the formatting is the same within any given column. A date column, for example, should only contain formatted dates. 
6. Date Formatting: Dates should be in YYYY-MM-DD format. 
7. State and Country Formatting: If you wish to import into Zengine state or country fields, then you must use these values. (The full state or country name will be displayed in Zengine.) Otherwise, you should plan to import those fields into text fields or custom dropdowns where you provide the state or country names. 
8. Single-Select Field Formatting: for data in columns that will be imported to a Dropdown field, a Radio Button field, or a Checkbox field, the data must EXACTLY match one of the available options for that field (this is case-sensitive). Note that these should match the options in the Values column of that field, not the Labels column, in the case that they differ for a given field.
9. Checkbox Formatting: in addition to Rule 8 above, data to be imported into a Checkbox field in Zengine (which allows users to select more than one option) follows a specific requirement. If the data to be imported for a single record has more than one option that should be imported, each option must be on a separate line within the same cell in the .CSV file. (Using Excel, a line break within the same cell can be done by pressing Alt+Enter on your keyboard.)
10. Validation Rules: if a field in your workspace has any validation rules (such as minimum or maximum characters, a Text field set to only accept numbers, or something similar), ALL of the data in the column to be imported to that field must also match those validation rules. For more information on validation rules, see the article Field Advanced Options.
11. Required Fields: if a field in your workspace is required, then a cell in the column corresponding to that field cannot be left blank.
12. File Format: The file containing the data to be imported must be saved as a .CSV (comma-separated value) file. These files are usually opened and can be edited in a spreadsheet software such as Excel, but must be specifically saved as a .CSV file to be imported.
13. Files: At this time, you cannot import files as part of a data record.

Note: if your data to be imported violates Rule 10 (Validation Rules) or 11 (Required Fields), or if an Upload field (Rule 13) is a required field, consider importing your data as Draft records. Doing so will ignore all formatting and validation rule checks that run as part of the importing process. CAUTION is recommended when doing so, as any data that is badly formatted will be brought into your system and may be difficult to fix in Zengine - so ensure that all of your data follows the rules above as much as possible before doing so!

Importing Your File

Once you have prepared your file and saved it as a .CSV, it's time to import into Zengine.  

Start your Import

1. Navigate to the Data tab on the navigation bar and go to the form into which you would like to import data.  
2. In the top right corner, you will see a "Form Tools" button. 
3. Clicking this will bring up a dropdown which includes the option "Import."

Clicking this will bring up a page where you will select your file.  Choose the .CSV file you have prepared.

At this point, the system will process your file. This will take a few moments. When this is done, the system will notify you, "We've got your file!" Press Continue to proceed.

 

Mapping your Data

At this point, you will need to map your data.  This involves connecting the column headers in your .CSV file to the fields on the form you are importing data to. When this is done correctly, the system will understand which data item from each cell in your .CSV file should be imported to which field in Zengine. Each row will be imported as a different record.

In the table on this page, the first column (Column Name) contains the names of the headers in your .CSV file (the first row in your imported data). The second column (Sample Data) contains a sample of the data in the other rows in that column in your .CSV file (usually the first row of data). The third column (Field Name) contains a series of dropdowns where the existing fields in your workspace are listed; --Do Not Import-- will be the default selection in each dropdown until a selection is made.  At this point, you must map each of the imported column headings to an existing field in the workspace by selecting the appropriate field from each dropdown.

The system can attempt to automatically map any columns that have the exact same names as fields. So if you have a field "email" and a column header "email," the system will have mapped these for you.  You will have to manually map any in which the names differed, or for which the system could not identify a matching field.

To have the system attempt to automatically map column headings to fields, select the Guess button in the upper right corner. Selecting Reset will all of the fields that have been mapped.

For any fields where there is not a matching column header, the system will automatically set the field name dropdown to --Do Not Import--.  This means the system will skip this column and won't import any data into this field. You can override this if you want by clicking the dropdown and manually choosing a field.

When you have completed mapping your data, select the blue "Continue" button at the bottom of the page.

At this point, your import will be processed. This can take several minutes or longer, depending on the size of the file. You will receive a system notification when the import is completed, and you do not have to stay on the same screen to wait for it to complete.

If there are any issues with the data being imported (see Troubleshooting below), you will be taken to a screen showing the error type along with the row and column that contains the problematic data. From here you will be able to fix the data in the original .CSV file and upload the file again, or continue without importing the record containing the problematic data.

Importing Into Linked Form Fields

When importing information into a  Linked Form field, you must use the Zengine Record ID corresponding to the linked record that you want to link an imported record to. To retrieve this ID, follow these steps:

1. Open your workspace and navigate to the parent form containing the records already in the system that you want to link the imported records to. (For example, if you have a Profile form and an Applications form and are importing information into the Applications form, and wish to link the Applications records to be imported to corresponding records on the Profile form, navigate to the Profile form.)
2. Now we want to show the Record IDs for the linked records. To do so, use the Hide/Show columns button to show 'ID'.
3. You'll see the IDs as the first column of the record. Please note that the ID will only show up in the Data View, not when viewing the form view of a specific record.
4. At this point, in order to prepare your file for import, you'll want to export the records on this parent form. You should include the Record IDs and a few other fields that can be used to easily identify records (such as Applicant or Organization Name, or email address).
5. Once exported with the Zengine ID, you can use Excel or similar spreadsheet program to match the IDs on the parent form to the corresponding rows (representing records to be imported) in the .CSV file you're importing. (This is why including identifying fields in your export is useful.) It may be useful to label this column something like "Linked [Parent Form Name] IDs."
6. Once the records to be imported are matched up with the corresponding record IDs from the linked parent form, you can remove the additional identifying fields. Save your CSV file and prepare to import the data into Zengine following the steps from above.
7. When mapping your data to the fields, you will map the column heading containing the linked parent form record IDs to the Linked Form field (on the child form, to which you are importing data) that corresponds to the appropriate parent form. 
8. Map the rest of your fields and continue with the import.
9. Once imported, the records you have imported should automatically be linked to appropriate records on the parent form.

Troubleshooting

Importing data is simple in principle, but meeting all of the data formatting requirements and field validation rules can be challenging, especially for data that originated outside of Zengine. Please keep the following in mind if you encounter challenges:

• If ALL of the data in a records/row meets the criteria established (see Preparing Your File for Import above), the full row will be imported as a new record.
• If ANY data in a record/row fails in any manner, you will get an error message about which row(s) and column(s) failed the validation rules on the form or field. For instance, if the Last Name field is required on the workspace form and one of your rows does not have data in the Last Name column, that will fail. Or if one field is supposed to be a date and something else is in that cell, or the date is not formatted properly in your spreadsheet, it will fail.
• In that case, the Zengine Importer will display which rows failed. You will then have the option to (a) cancel the import, fix what is wrong, and rerun the import OR (b) do not import the rows/records that contained data that failed.
  • The information displayed will contain a generic message indicating the type of error that was flagged by the bad data.
  • We recommend trying to fix your data and rerun the import as much as possible; if rows are skipped during import because of bad data, it can be difficult to keep track of which rows were imported and which were not.

If you continue to encounter problems and can't solve them after consulting the information in this article, please contact the Zengine Support Team.