This article provides a detailed guide to using the Data Map Template designer to import your data.

The Data Map Template or data template model is a series of expandable and collapsible fields. Its configuration and design will determine what data gets imported and where into VC. Each field specified in the Data Map Template Designer will add a set of columns in the final Data Map spreadsheet. Each specified field here will add all columns necessary to import a complete record into the given destination. For example, when you specify a form, you are instructing VerticalChange to generate a Data Map with columns for every piece of information recorded in that form. Users will then add and align their data directly into the columns of the finalized Data Map Template spreadsheet.

The relationship between the Data Map Template and the resulting Data Map can be confusing. If you find yourself wondering what the effect of adding or removing a field will be as you read this section of the guide, it may be helpful to refer to the Reading a Data Map and Designing a template to match your data sections below.

When you create a new Data Map Template, you will be brought to the Data Map Template Designer. There will be empty data fields arranged as pictured to the right (the designer will look slightly different if your implementation uses locations). Fields that require additional action will have a yellow exclamation point next to them. These fields must either have some information entered or be removed (see adding and removing) before the Data Map Template will be ready for use. The numbers next to the fields are the number of fields in the next step of the hierarchy down from that field. For example, the [1] to the right of “forms” indicates that this Data Map Template currently involves creating and/or modifying data for 1 form template (the details - i.e. which form template - can be accessed by expanding the 0 below forms). The fact that “forms” is below a 0 below “contacts”’ indicates that the specified form will apply to the first identified contact in the import (i.e. contact 0).

The types of fields you can modify and how to modify them are listed below in the order they appear in the template designer below the data_map_template entry.

The contact map contains all categories pertaining to contacts (e.g. participants, clients, etc.) within VerticalChange.

First, some disambiguation: In discussing the Data Map Template, ‘contacts’ refers to a level in the Data Map Template hierarchy. Entities in VerticalChange that are normally referred to as ‘contacts’ will be referred to as ‘groups or individuals’.

A ‘Contact’ in the context of the Data Map Template is a set of commonly-identified (i.e. identified by the same UID or EID column in the Data Map) groups or individuals to which the designer of the Data Map Template wishes to make a specific set of changes. Each contact specified in the Data Map Template will create a merged cell in the row-one header of the Data Map. All of the data entered into a given row under that header will be assumed to apply to the same group or individual in VerticalChange. Adding additional contacts to the Data Map Template, therefore, allows you to create a Data Map that will create or update data for multiple groups or individuals on the same row. If you do not expect to need to do this, it will not be necessary to add additional contacts.

When you open the Template Designer and expand the contacts field, you will see an expandable field named ‘0’ below it (see picture above). That 0 represents the first contact that you intend to create or modify; each Form, Staff, Enrollment, ContactSubType field in the Data Map Template under 0 will add more columns to the Data Map under the ‘contact 1’ row-one header. Data entered in the resulting columns of the Data Map will be applied to the group or individual identified under the group or person common fields row-two subheading for a given row of entered data. As you add more contacts in the designer, by duplicating ‘0’, they will be numbered sequentially (i.e. the second contact is 1, and the third 2). The sets of columns that these additional contacts add to the import template will not be related to the data in the set of columns added for contact ‘0’. This enables you to do very different things to different groups or individuals from one row.

For more information, and an example of the effect of adding multiple contacts and the relationship between the template and the Data Map, please see the note on designing a template below.

First, some disambiguation: Similarly to ‘contacts’ above, ‘form’ and ‘forms’ in this document refer to the field (the 0 to the right) and level of hierarchy (“forms” to the right) in the template designer respectively. Specific instances of a form (i.e. data attached to a contact or program) will be referred to as ‘form results’ while specific form templates (i.e. the things created in the form designer) will be referred to as ‘form templates’.

Forms allows you to specify which form template(s) you want to create or modify existing results for in the import. Each form you add to a template will add columns for every piece of data tracked in the selected form template. Note that it is nested below contacts, so any forms added here will only affect the contact they are nested under. You may add the same form template to different contacts or even multiple times to the same contact if you want to import multiple form results per row of the Data Map. Choose the name of the form template from the dropdown and a program from the program dropdown. The program you choose here will not affect the performance of the import - you will still have to specify the program by entering its UID in the uploaded file for each row. See "Program IDs" below for details.

Forms can be duplicated in the template designer in the same way as contacts. To add a second form to the same contact, duplicate form 0 in the way described for contact 0 below.

Staff allows you to assign a user to a contact, modifying the ‘assigned to’ field with the importer. This will add a single column to the Data Map that can be populated with a staff UID (staff UIDs are available in the URL of each staff person's profile in the Staff Module - which will be accessible through the left-hand sidebar if you have the required permission). If you do not have access to the staff module and wish to assign staff to a contact via import you will need to get staff UIDs from someone with that access.

Enrollments allows you to enroll or disenroll a contact from a specific program. When you add an enrollment field you will specify a program by choosing its ID number or its slug (which can be determined or set using the slug field, which is accessible by selecting a specific program in the Programs Module through the left-hand sidebar). Unlike the form field above, the selection of a specific program in the template designer is very important for the enrollment field; each enrollment field will only work for the selected program. Add one per enrollment that you wish to make. (See also: Enrollment fields)

ContactSubTypes allows you to specify which contact you are creating or modifying by selecting ‘person_common_fields’ or ‘group_common_fields’ for individual or group contacts respectively. One of these is necessary for each contact you add to the Data Map Template because this identifies the group or individual referenced on a given row of the Data Map for those cells under a given contact’s row-one header. You can also add or make updates to one or more contact subtypes for the specified contact by duplicating ContactSubTypes field 0 and choosing an additional CST.

IMPORTANT CST NOTES:

The relationships field in the Data Map Template Designer allows you to add a section to the import template that will associate two contacts or add a contact to a group. Add one for every such association you wish to make per row of your Data Map.

Note that ‘Relationships’ is not nested under contacts in the image above. Relationship imports are not implicitly tied to any contact that shares the same row. Each relationship field added to your template will require a Unique ID or External ID for each of the two contacts you intend to relate to each other.

The Data Map Template starts with an empty version of every action you can set the importer to perform. The way to get more (for example in order to create a template that allows imports into two different form templates) is to duplicate an existing one and then modify the new forms field to specify the second form. A field may be removed using the remove button. Both options are accessible by clicking the box icon to the left of a form, contact, staff, enrollment, or contact subtype index (e.g. the 0 pictured above).

Please remove unnecessary fields within the Data Map Template Designer; unnecessary fields found within the Data Map Template can cause errors during the import process. However, since the only way to add a field is to duplicate an existing one, the only solution for incorrectly removing the last field of a given type is to abandon your work and rebuild the template from scratch; be careful when removing fields.

The importer V2 is very flexible. You can design a template to fit the shape of your data by manipulating the number of contacts and the arrangement of forms, enrollments, and contactSubType fields within them.

For the example on this page, assume that your source data includes information with family, parent, and up to two children’s data all arranged on one row, you don’t need to run separate imports for each component. Instead, you could create a single Data Map Template with four contacts and three relationships fields. The images of the Data Map Template Designer on this page are broken up for convenience but would appear continuously in the designer in the order they are mentioned in the text.

Contact 0 (above, right) will create columns to be populated with the family information, including the program enrollment information, group_common_fields CST, and the Family CST; contact 1(left) creates space for the parent’s data: adding an intake assessment, program enrollment information, the person_common_fields CST, and the parent CST; and contacts 2-3 (below, right) generate columns for the up-to-two children: the person_common_fields CST and the child contact type. Then, a series of relationship fields - one for each of the individual contacts - (below, left) allow space for each individual contact to be related back to the family.

The entire family record can thus be entered on one row of the resulting Data Map - simplifying the prep work for data import.

The Data Map that results from the previous page’s example Data Map Template is represented below. Since this Data Map Template includes a form, 8 CSTs, 4 program enrollments, and three relationships, the resultant Data Map is several hundred columns wide. In the interest of avoiding eye strain, this representation simplifies the row-2 subheader for readability and length and condenses each into a single column - this means that the row-three subheaders specifying data are omitted. Also note that contact 0 from the template has been renamed contact 1, contact 1 is named contact 2, and so on.