Import your data into ChurchSuite
In this article
At its most basic level the Address Book module serves as the repository for all your adult contacts - all those with whom you're in contact with as a church or charity, regardless of their level of engagement with your organisation.
This article explains how you can easily import your existing contact data into ChurchSuite that you've exported from another system. We encourage you to familiarise yourself with the content of the article to help prepare your data ready for import. The ChurchSuite Support team are happy to help you with importing your data too - contact us at firstname.lastname@example.org - but if you're ready to get started yourself, here's how...
The ChurchSuite "importer" in the Address Book can handle data presented in a variety of layouts, or you can manually 'manipulate' your existing data to suit one of these two layouts if you prefer.
Layout 1. Where each person is in a separate row in your datafile
This is where your datafile includes both adults and children, with each person in a separate row in the file. If not already present, you can easily add a "child" column to your datafile (see example below), so that the Address Book importer can distinguish which rows are to be imported into the Children module and which rows are to be imported into the Address Book.
In this example, John, Mary and Craig will be imported to the Address Book, and David, Maisey and Jack will be imported to the Children module. Note that ChurchSuite will never assume people links from data in different rows, so while John and Mary have a 'married' status and are likely married to one another, the two contacts will be added but not linked - however, you can use the "potential couples" report to easily link them together after import, ensuring that you are in full control of your data.
Note that with this layout you can optionally break the file into two - one for adults and one for children - and perform a separate import of children into the Children module, as explained in our related support article. Doing so has the distinct advantage of enabling you to import a wider range of children data into the full range of Children module fields (only basic child information fields are available in the Address Book importer - see full field list at the end of this article); you can then use our "potential parent linking" report after the import is completed to easily link children to their parents.
Layout 2. Where spouse/partner data is in the same row in your data file
This is where your datafile includes adults whose linked spouse/partner is included in the same row in the file. Unlike the example above where John and Mary were in separate rows, in this example - row 2 - the importer will import John and Mary as two distinct contacts from the same row, but they will be automatically linked together with their spouse/partner relationship because their data is in the same row.
Again, children can be imported to the Children module if distinguished by a "child" column in the datafile (see above), or you can optionally break the file into two and import adults and children separately.
Note that in this layout you can only specify basic spouse contact details - title, first name, full name, last name, sex, email and mobile. Additionally, the importer will copy the following contact data onto the spouse - address, communication options (e.g. receive email/sms etc.) custom field data, last name (if spouse last name is not specified in the datafile), marital status, privacy settings (e.g. name/address is visible etc.), site, telephone, and tags. If you have more detailed spouse data to import you should use Layout 1, separating couples so that each partner has their own row in the datafile, affording you the full range of contact import fields listed at the end of the article.
Preparing your data
Here's a simple checklist of things to do before importing your data.
1. Make sure your data is in the right format and file type
To import data to ChurchSuite it needs to be in the form of a .CSV file, using a comma as the delimiter and in UTF-8 format. Spreadsheet applications such as MS Excel, Apple Numbers and Google Docs allow you to easily save data as a CSV file in the correct format. Similarly, many 'contact management' applications allow you to export data as a CSV file.
UPPERCASE or lowercase or Mixed Sentence Case?
When preparing your CSV file, we encourage you to use mixed sentence case formatting, rather than UPPERCASE formatting, especially for first name and last name fields - in this way, when you are using ChurchSuite's communication 'merge fields' you can personalise communications as "Dear James" rather than "Dear JAMES".
2. The first row must contain column header labels
The ChurchSuite importer will use the column header labels to map the data in each column of the CSV file to the correct field in ChurchSuite. You will be able to override the default mapping prior to completing the import - perhaps to correct a wrongly-mapped field - but by using ChurchSuite's field-naming convention (see the full list at the end of this article), your data will be auto-mapped to the correct ChurchSuite fields, making the process even simpler. Your 'people' data must start from row 2 in the CSV file.
Do not use the same column header label more than once in your CSV file, otherwise columns will be ignored during import - column header labels in row 1 only must be uniquely-named.
3. Review your Address Book module settings
Ensure any Optional Contact Fields used in your CSV are first enabled in the Address Book module's settings (accessed via the cogwheels icon in the top right corner of the module) - you may find it helpful to first enable all optional fields so that they're available to the importer and then disable any that are not needed after the import has been completed.
4. Set up custom fields in ChurchSuite before import
Ensure that any custom fields and custom field values are correctly set up in ChurchSuite ready to receive your data - see the related support articles for further information about custom fields. For any custom fields that are set as required in your Address Book module's settings (accessed via the cogwheels icon in the top right corner of the module), valid values must be supplied for every row in your CSV file.
For "checkbox list" (multi-select) type custom fields - where a contact may be assigned multiple options, each option should be presented comma-separated in your CSV file - like this example, where column C and D are both multi-select custom fields - both these custom fields and all the possible options for each must be set up in ChurchSuite before import; and the option-naming convention must be consistent between your CSV file and ChurchSuite.
Note: when preparing a CSV file that contains both adult contacts and children, you can only map columns in your CSV file to Address Book module custom fields. You should therefore refrain from specifying custom field values for rows in the CSV file that relate to children as the data will not map to Children module custom fields in the same way.
5. Review your default communication options and privacy settings
Unless explicitly specified in your CSV file, ChurchSuite will assign the default Communication options and My ChurchSuite & Privacy settings that are specified in your Address Book module's settings (accessed via the cogwheels icon in the top right corner of the module) to each contact during import.
6. For data being imported as Tags
You can optionally use a special column header label prefix of tag_ so that ChurchSuite will auto-map that column as a Tag. See our related support articles for further information about Tags. There's no limit to the number of columns in a CSV file that can be imported as Tags. The prefix is removed when the tag is created.
For example, tag_Member will create a 'Member' tag and assign it to each person whose column value is 1, yes, true, y, or * (case sensitive). A blank value (or 0, no, false, or n) is ignored and the person is not tagged. In the following example the tag "Member" in column C will be assigned to each contact in rows 2 to 6 - all of these values mean the respective contact should be tagged. By contrast, the tag "Holiday Club" in column D will not be assigned to any of the contacts in rows 2 to 6 - these are all examples of values that would not result in a tag being assigned, including a blank value in cell D6.
Multiple tags can also be assigned from a column that contains comma-separated tag names, For example, a column header label of tag_Role and a value of 'Leader, First Aider' will assign that contact to a Leader tag and to a First Aider tag. In this context the column header label name is not saved. Make sure you use a consistent tag-naming convention throughout your CSV file to avoid unexpected variations on a theme! Here's some examples in columns C and D - some contacts will be assigned multiple tags and some just a single tag.
Note that where your datafile has a contact and their spouse in the same row, any tags specified in the row will be identically assigned to both partners. If you wish to assign different tags to each partner you should separate people into their own row in your datafile.
7. For data being imported as Key Dates
You can optionally use a special column header label prefix of kd_ so that ChurchSuite will auto-map that column as a Key Date. See our related support articles for further information about Key Dates. There's no limit to the number of columns in a CSV file that can be imported as Key Dates. The kd_ prefix is removed when the Key Date is created. Each key date column can only contain one date value per person. A key date may optionally contain a key date 'Description' too - for example:
Column Header: kd_First Communion
Data: 23/07/2019 Bishop Alison presiding
Key Dates must be formatted in either the ISO format (yyyy-mm-dd) or your local date format (e.g. UK: dd/mm/yyyy or North America: mm/dd/yyyy).
Note that invalid Key Dates cannot be corrected during the import process. If Key Date errors are detected you can either select to remove those contacts and re-import them separately with fixed data; or you should cancel the import and re-imported afresh once the invalid Key Dates are fixed.
8. For data being imported as Notes
You can optionally use a special column header label prefix of notes_ so that ChurchSuite will auto-map that column as a Note. See our related support articles for further information about Notes. There's no limit to the number of columns in a CSV file that can be imported as Notes. The notes_ prefix is removed when the Note is created. If multiple columns of notes are to be imported, use the format notes_<note-name> for each note column, e.g. 'notes_pastoral', notes_integration'. For each person with a note column entry in the CSV a separate note will be added, but the suffix name <note-name> is not saved.
9. Small groups and serving ministries
Where a person's small group(s) or serving ministries are recorded in your CSV file, you may find it helpful to import these as Tags in the first instance. Later, having completed the import, you can easily re-create those groups and ministries in the respective Small Groups and Rotas module, and then quickly bulk-assign people to their correct groups or ministries/teams from those Tags.
10. Date format consistency
All dates in your CSV file, including dates of birth and 'date' type custom fields, must be formatted in either the ISO format (yyyy-mm-dd) or your local format (e.g. UK: dd/mm/yyyy or North America: mm/dd/yyyy).
11. All rows in the CSV file will be imported into the Address Book module
Every person in your CSV file will be imported to the Address Book module, regardless of the person's date of birth, unless the "child" field is specified in your CSV file. Note that you can easily move children to the Address Book (and vice versa) after import if you later spot a mistake. In this example, John, Mary and Jack will be imported to the Children module (regardless of any date of birth that may also be specified) and any Address Book-related fields in their data that don't apply to the Children module will be ignored. However, Susan and Peter will be imported to the Address Book (regardless of any date of birth that may also be specified) and any children-related fields in their data that don't apply to the Address Book module will be ignored.
A full list of support fields for the Address Book importer is provided at the end of this article. A full list of supported Children module importer fields are provided at the end of the related support article.
12. Linking people
ChurchSuite treats each row in the datafile as a separate person - we never derive data from people in other rows, and neither are people in other rows auto-linked by the importer. For example, even if a couple with identical contact details or last names are listed in two rows in your datafile - a seeming 'couple' - ChurchSuite never assumes a relational connection.
Additionally, personal data is never derived. For example, the importer will not determine that a contact's unspecified sex is "Male" because their Title is "Mr" or their spouse is "Female" - we only use the data explicitly specified in your datafile. This is especially important when thinking about linked family members - spouses/partners and parents and children. The only time a relational link is made automatically is if a contact's spouse/partner is specified in the same row (as seen in Layout 2 earlier in this article); otherwise no spouse/partner link is made. Similarly, all imported children will not be linked to potential Address Book contacts (parents) during the import process - regardless of how the datafile layout is presented. However, after import you can use the Potential Parent Match report (in the Children module's Reports section) and the Potential Couples report (in the Address Book module's Reports section) to quickly and easily link children to a parent in the Address Book and link contacts to their spouse/partner. Linking a child to one Address Book parent will auto-link the child to the other parent by virtue of the parent contact's marital status linking.
13. Multi-site considerations
When importing multi-site people data, make sure you set up your Sites in ChurchSuite first, and be sure to specify "sites" as a column in your datafile so that each person is assigned to their correct site/s during the import process (the site-naming convention in your CSV file must match the site-naming convention used in ChurchSuite). Any contacts without a site specified will be imported as "All sites", but their site can be later changed if necessary.
Important: To avoid unexpected errors during import, make sure that the logged in User performing the import has "User Site" permissions for all of the sites specified in the CSV file - a User can only import/create data in sites that they themselves have permissions for. A validation error will occur for all rows with an unexpected or invalid site specified; including a site specification that the User is not authorised to access.
14. International support - accented characters
You may experience an issue with accented characters during import. This will be evident in the upload "preview" stage (see below) - you may see � characters in place of accented characters e.g.
This issue is generally restricted to CSV files created using Microsoft Excel. To work around the issue, Cancel the import and follow these 'workaround' steps. While you can still prepare your data in Microsoft Excel, you will need to use alternative software to produce the final CSV file(s) in the correct UTF-8 format. For Mac we recommend using Apple's native "Numbers" spreadsheet application. For Windows, we suggest using "OpenOffice". Working within the alternative software, re-save your data in CSV format and then import the new CSV file into ChurchSuite.
15. Need some inspiration?
You may find our Address Book CSV template file useful - Example contact import CSV file - click to download and open in your preferred spreadsheet application.
Importing your CSV file
From the Contacts section of the Address Book module click Import contacts.
Next, make sure your CSV file is the right format - see the previous section in this article. The Import contacts page includes a helpful section titled Creating you CSV file where you can Download an example CSV file and view a list of supported Field names and the expected valid data format for each. A full list of the accepted fields with the relevant header information can be found at the end of this article.
You do not need to have a column for every field - ChurchSuite will only import those fields you supply in your CSV file; however you must ensure every incoming field that you supply in your CSV file is correctly "mapped" to a ChurchSuite field (otherwise it won't be imported) and is in a valid format - this is explained later.
The minimum data required for each person is their First name and Last name. Make sure that these two fields are the very first two columns in your CSV file. For any custom fields that are set as required in your Address Book module's settings, valid values must also be supplied for every contact in your CSV file.
Please note that it's not possible to import profile images - instead, these must be uploaded separately against each person's profile after the data is imported. Contacts and parents can also easily upload and manage their own and their children's profile images in the member-facing My ChurchSuite platform.
Once you are ready to proceed - and with your CSV file ideally located on your desktop - click Choose file to browse to your CSV and then click Import CSV File.
The first 5 records of your data are now 'previewed'. Note the CSV Header column - this can be helpful in ensuring ChurchSuite correctly maps each field in your CSV file to the correct field in your ChurchSuite modules. If you've followed ChurchSuite's suggested field-naming convention, your CSV Headers it will be auto-mapped to the correct field in ChurchSuite (shown in the Import As column).
You can manually change the Import As selection for any field by using the drop-down field selector. Items marked with a yellow warning symbol will not be imported and require your attention. You can either leave them as Do not import or select the appropriate Import As field from the drop-down list. In the following example "note_2" is not a recognised import field name, but needs to be imported as "Notes" (see earlier in this article).
Having carefully reviewed the preview select Import All Records button at the bottom of the page to complete the upload.
Your incoming data is validated during the upload. All valid rows are distinguished by a green tick to the left of each person's name (example below).
A yellow warning triangle next to a person's name indicates there is invalid data. Details of the invalid data is summarised in the Errors column. Note the Action menu to View or Edit any contact, or to Remove a person from the import altogether.
You can easily switch between viewing all uploaded data, just Valid data or just Invalid data.
Selecting Edit from the Action menu opens a pop up of all the person's details, including details of any invalid data. Errors (shown in red) must be resolved before that person can be imported. Click Save at the bottom of the pop up to save any changes made. If all errors for a person have been resolved they will show in the list with a green tick, indicating a valid record ready for import. Continue working down the list and resolve the errors for each person in turn.
Note that you can Cancel an import entirely at any time - perhaps if you spot a catastrophic error affecting all data that may be better fixed within your CSV file - click Cancel and repeat the steps above to re-upload your corrected CSV file.
You can Process valid records at any time - processed records will be imported and the Status of those records will change from Pending to Processing to Imported. You can easily filter the list to view people with a particular status - Pending status records have not yet been processed/imported.
You can also Pause an import at any time.
You can then Resume a partial import by returning to the Import contacts section and click into the Imports tab to Resume or Cancel the partial import.
Each time you click Process to import valid records, a pop up 'success' message confirms - in the example below, 12 people were successfully imported - and their status updates from Pending to Imported.
Each time you click Process the imported people are assigned to an Import Tag in the Tags section of the respective Address Book or Children modules - the naming convention "Import [date and time]" is used, making it easy to identify newly-imported people (and to bulk-delete them if the import didn't go as expected!) You can safely delete these tags after import once you are satisfied that your imported data is correct.
Import file specifications - Address Book module
|Field||Imported Into||Sample Data|
|title||will be imported into the Title field||Mr OR Mrs OR Miss OR Ms OR Dr OR Rev OR Sir OR Lady|
|full_name||broken into First Name and Last Name fields||Joe Bloggs or Bloggs, Joe|
|first_name||will be imported into the First Name field||Joe|
|middle_name||will be imported into the Middle Name field|
|last_name||will be imported into the Last Name field||Bloggs|
|formal_name||will be imported into the Formal Name field||Joseph|
|maiden_name||will be imported into the Former Name field|
|known_as||will be imported into First Name and First Name becomes Formal Name||Joe|
|sex||will be imported into the Sex field||m OR f OR male OR female OR u (unknown)|
|date_of_birth||will be imported into the Date of Birth field||31-01-1970 (i.e. dd-mm-YYYY)|
|marital||will be imported into the Marital Status field||NULL OR single OR engaged OR married OR cohabit OR separated OR divorced OR widowed|
|full_address||breaks on commas into Address, Address 2, City, County and Postcode fields||1 Queens Drive, Beeston, Nottingham, Notts, NG1 1AB|
|address||will be imported into the Address field. NOTE: this field will be ignored if any 'house_x' fields are present|
|address2||will be imported into the Address 2 field|
|address3||will be imported into the Address 3 field|
|city||will be imported into the City field|
|county||will be imported into the County/State field||County or State/Province|
|postcode||will be imported into the Postcode/Zip code field||Postcode or Zip code|
|country||will be imported into the Country field|
|house_name||House name, with house number & street imported into Address field||The Cottage => The Cottage, 45 River Lane|
|house_number||House number, with house name & street imported into Address field||45 => The Cottage, 45 River Lane|
|house_street||House street, with house name & number imported into Address field||River Lane => The Cottage, 45 River Lane|
|telephone||will be imported into the Telephone field|
|work_telephone||will be imported into the Work Telephone field|
|mobile||will be imported into the Mobile/Cellular field|
|will be imported into the Email field|
|married_to||Imported into Married Status field as married, if any name is present||Jane (is married to this contact)|
|couple_first_names||NEW CONTACTS CREATED for BOTH names||Jane & Joe|
|married_notes||Imported into the Marital Status field as married, if the word married is present||married to Jane|
|spouse_first_name||NEW CONTACT CREATED for Spouse||Jane OR Jane Smith|
|spouse_last_name||NEW CONTACT CREATED for Spouse||Last name of spouse|
|spouse_email||NEW CONTACT CREATED for Spouse||Email of Spouse|
|spouse_mobile||NEW CONTACT CREATED for Spouse||Mobile of Spouse|
|child||CHILD ONLY - determines if contact or child||child - will be imported to Children module|
|school||CHILD ONLY - imported into School field||Town Primary school|
|medical||CHILD ONLY - imported into Medical field||Has a serious nut allergy|
|medical_short||CHILD ONLY - imported into Medical (short) field||peanut allergy|
|special_needs||CHILD ONLY - imported into Additional Needs field|
|doctor_details||CHILD ONLY - imported into Doctor field||Dr. S Rudrashetty, 1 Surgery Road, Nottingham (children are imported to Children module)|
|info||CHILD ONLY - imported into Additional Info field|| Additional Information
(children are imported to Children module)
|consent_use_internal||CHILD ONLY - imported into Internal Use Consent? field|| 1 OR Yes OR True (Consent granted)
0 OR No OR False (Consent denied)
Null or Empty (Consent unknown)
|consent_use_external||CHILD ONLY - imported into External Use Consent? field|| 1 OR Yes OR True (Consent granted)
0 OR No OR False (Consent denied)
Null or Empty (Consent unknown)
|job||will be imported into the Job field|
|employer||will be imported into the Employer field|
|notes||will be imported into the Notes field|
|tags||will be imported into the Tags field||Member, Leader|
|keydate||will be imported into the Key Date field||Name in CSV header, Date in row|
|public_login||will be imported into the Allow My ChurchSuite login? field||1 OR 0 (Yes OR No)|
|receive_general_email||will be imported into the Receive general emails field||1 OR 0 (Yes OR No)|
|receive_general_sms||will be imported into the Receive SMS field||1 OR 0 (Yes OR No)|
|receive_phone||will be imported into the Receive phone calls field||1 OR 0 (Yes OR No)|
|receive_post||will be imported into the Receive post field||1 OR 0 (Yes OR No)|
|receive_rota_email||will be imported into the Receive rota reminder emails field||1 OR 0 (Yes OR No)|
|receive_rota_sms||will be imported into the Receive rota reminder SMS field||1 OR 0 (Yes OR No)|
|public_visible||will be imported into the Name is visible? field||1 OR 0 (Yes OR No)|
|public_visible_address||will be imported into the Address is visible? field||1 OR 0 (Yes OR No)|
|public_visible_telephone||will be imported into the Telephone is visible? field||1 OR 0 (Yes OR No)|
|public_visible_mobile||will be imported into the Mobile is visible? field||1 OR 0 (Yes OR No)|
|public_visible_email||will be imported into the Email is visible? field||1 OR 0 (Yes OR No)|
|sites||will be imported into the Sites field||Site name/s specified exactly as named in Administrator > Profile, with multiple sites specified comma-separated. An empty sites value is treated as "All sites"|
|student_full_address||breaks on commas into Address, Address 2, City, County and Postcode/Zip code fields||Raleigh Park, Faraday Road, Nottingham, Notts, NG7 2EG|
|student_address||will be imported into the Address field|
|student_address2||will be imported into the Address 2 field|
|student_address3||will be imported into the Address 3 field|
|student_city||will be imported into the City field|
|student_county||will be imported into the County/State field||County OR State/Province|
|student_postcode||will be imported into the Postcode/Zip code field||Postcode OR Zip code|
|student_country||will be imported into the Country field|
|student_telephone||will be imported into the Telephone field|
|student_university||will be imported into the University field|
|student_course||will be imported into the Course field|
|student_year_start||will be imported into the Start Year field||yyyy|
|student_year_end||will be imported into the End Year field||yyyy|