This article provides a basic overview of the import process designed to act as a supplemental guide to training, as well as links to help pages on the specific aspects of the VerticalChange data importer (occasionally referred to as the importer V2 or importer 2.0).
This guide will cover permissions and user access controls, Data Map Templates (the abstract mapping structures used to connect the input data to your forms and contacts in VerticalChange), Data Maps (the spreadsheets into which you will enter your data for upload into VerticalChange), and include information on how to format and organize your data for import.
More detailed articles on specific aspects of the importer
The Data Map Template designer: A review of the details of creating a data map template and details on how to design a Data Map Template that matches the shape of the data you wish to import.
Working with exported Data Maps and entering data: How to read Data Map headers and enter data into a data map. Also includes notes on imports for different VerticalChange data field types and a discussion of how to use external and VerticalChange unique IDs.
Importer Tips and Best Practices: Best practices for running imports. Covers reversions, what to do when importing large amounts of data, and what you need to do after updating a form template.
Setting up permissions and access
Access to the importer is gated behind several importer-related permissions (pictured below). Contact Vertical Change to enable the importer V2 if it is not already turned on for your account. Once that is done, you may add the four importer-related permissions below to staff permission sets.
Manage importer imports allows a user to modify importer templates and create Data Maps.
Manage importer reversions allows a user to undo imports creating new data. (see the reversions section for more details on the process)
Upload data for import allows a user to upload files and run imports based on those files making use of pre-existing templates and Data Maps.
View all importer data allows a user to see files, jobs, logs, job history, etc. created by others.
Program or location-based restrictions on a user’s capacity to access and modify data do not apply to the importer V2. This means that a user given access to the importer will be able to modify data that they could not otherwise see or modify based on their permissions.
The only restriction on user access that will limit an import is field access levels. A user cannot import into a field for which they lack "edit" access.
General overview of the import process
The importer V2 can be accessed from the importer module, accessible from the left-hand sidebar of the VerticalChange application. Using the importer involves several steps:
Step 1: Creating a Data Map Template
First, navigate to the Data Map Templates tab and select the + Template button to begin the template design process. Enter a name, a description, and select a template model from the dropdown. You will want to use Contact Template Model 1 unless your implementation uses locations. In that case, you will want to use Contact Template Model 1 With Locations. Select ‘Create’.
This will direct you to the Data Map Template Designer, which will allow you to specify the Data Map Template’s overall structure, which will inform the importer of the modifications you intend to make. Here you will identify whether you intend to create/modify certain form templates’ data, assign staff, enroll contacts in a specific program, create/modify contact subtype (CST) data, and/or create relationships between contacts. See Using the Data Map Template designer for details.
Step 2: Creating a Data Map
Once you have created an import template, you will use that template to generate a Data Map. The Data Map will contain columns into which you can add the data you intend to import. You will not need to modify the Data Map as part of this process, only specify a template from which VerticalChange will generate a map. Select + Map, enter a name and description, select the Data Map Template that you wish to use from the drop down, and select ‘Create’. Select ‘Save’.
Download the Data Map using the download arrow to the left of its name in the list of Data Maps.
Step 3: Enter your data into the Data Map
See Working with exported Data Maps and entering data for more information.
Step 4: Save and upload the file
Once you have entered your data into the Data Map and saved it as a CSV file, navigate to the files tab, select Choose Files, and upload your Data Map.
Step 5: run the import
Navigate to the Imports tab. Select + Import.
Give your import a name, designate a Data Map (referred to as a field map) and the input file you just uploaded. Then choose a run type and indicate whether the log should include additional details by checking or leaving blank verbose output (verbose output is useful for troubleshooting a failed import) and select run. You may leave the ‘Number of rows to import’ field blank unless you are importing more than 10,000 rows or importing a single row as a test.
Once the import is complete, a log will appear on the Logs tab with the import’s name, the type you selected (trial or final), and its outcome status. You will also receive an email notification. “Success” means that the import did not encounter any fatal errors; “failure” means that it did. Success should be verified by checking at least one row of imported data. Failed final imports will still create data in the system - up through the point at which they.