Learn about our newest features and enhancements!
Data Importing: How to Import Contact - Household Data
Authored by: Megan Gill
 on 10/17/2024 3:40:00 PM

Introduction

You may identify the need to import Household contacts to your CharityEngine instance. Please note, the use of households should be carefully considered when establishing import, set-up and long term management of people vs. household records. Adding household based contact records can be accomplished through the Workflow & Automation Importer tool.

Table of Contents

Prerequisites

  • CRITICAL NOTE: Preparing your data is an important exercise to ensure your data is properly formatted and will be prepared for importing
  • NOTE: In order to import Household type records the minimum required fields will include Household Name; if your data does not contain Household Name, you will need to create business rules to append a placeholder value (i.e. "No Name"). Please note, repetitive usage of a placeholder will create duplicate name records and may impact your data governance and CharityEngine matching logic. 
  • Determining Business Rules: When using households, it is important to understand the features, functionality, and downstream reporting associated with households and those members associated with a household. Please see our article Contacts: How to Create and Manage Household Contact Records to learn more about householding within CharityEngine. 

Prerequisites - Best Practices for Data Preparation

When preparing your data, data cleansing practices are incredibly important to ensure you are importing good, clean data for your database. Here are a few examples to assist with data cleansing prior to import. 

Step 1: Ensure basic information is correctly formatted, including:
    1. -Does each row contain a household name value (required as the minimum field for importing to Contact - Household table)
      1. Please review for rows containing null values within your data import as these may result in importing errors
    2. -Is the mailing address properly formatted - if the contact contains Address Line 1, Address Line 2, City, State, Postal Code, and/or Country, all address fields will be required
      1. CharityEngine recommends use of a full mailing record for best data practices. If the full address does not exist, best data practice is to leave full address as null.
      2. If the record contains partial address data elements and still require import, below are recommended placeholders. Please note, the use of these placeholders will create duplication and impact downstream reporting and functionality usage
        1. UNITED STATES
          • Street 1: 123 Missing Street
          • Street 2:
          • Postal Code: 00000
          • City: MISSING
          • State: AA
        2. ALL OTHER COUNTRIES
          • Street 1: MISSING
          • Street 2:
          • Postal Code: 000000
          • City: MISSING
          • State: AA
  2.  
    1. -Is the email address properly formatted and include the presence of "@" and a ".com/org/net" etc.
    2. -Are phone numbers properly formatted (most formats are acceptable including 201.555.1234, 2015551234,(201)555.1234, 201-555-1234)
    3. -Have Head of Household and/or Spouse contract records been created in CharityEngine - and are assigned to the assigned Household Contact Id
Step 2: Leverage Excel or other tools to identify duplicate contact records
    1. Conditional Formatting in Excel:
      1. -Select the cells you want to check for duplicates
      2. -In Excel click Home > Conditional Formatting > Highlight Cell Rules > Duplicate Values
      3. -In the box next to values with, pick the formatting you want to apply to the duplicate values, and then click OK



    2. Removing Duplicates in Excel:
      1. In Excel click Data > Remove Duplicates
      2. In the popup box, select your columns for matching values


    1. Sort & Filter in Excel: Leverage the Excel Sort and Filter options under the Data Ribbon 
  3.  
    1. Text to Columns Excel features to modify data including splitting fields (i.e. splitting a first name and last name) 
Step 3: Managing fields that require values
    1. -If your household name does not contain a value, you will need to determine the appropriate value to include as a placeholder. For example, a null name may be reflected as "Missing Name". Please proceed with caution as repetitive usage of a placeholder can create duplicative values and may impact contact merging as well as management of data governance. CharityEngine strongly recommends evaluating usage and evaluation of data that may be missing name elements for effectiveness. 
Step 4: Email Opt Out/Undeliverable historical records
      1. In order to maintain strong email sending practices, users should take care to ensure that previous email (or other communication) opt out fields have been identified. If a donor has indicated previously that they no longer wish to receive email, maintaining that commitment is critical for good email sending practices. Failing to set the appropriate opt out status can result in degraded IP/email domain reputation including deferred email, delivery to spam, or email blocking by the email service provider.
Please Note: CharityEngine does not support data cleansing in basic data migration packages. Please ensure you take care to ensure you have properly reviewed and corrected any data elements. If you are interested in learning more about data cleansing support, please contact your account manager for details. 

Preparing your file import

When importing households, preparation is an important activity to ensure you have clean data for your CharityEngine database. When importing Households for your contact records, the minimum requirement is Household Name. 

The following table will provide you with basic household data elements for importing. Provided below are details for the translated CharityEngine Field name. Please also notate importing requirements as outlined within Description. 

Table Import Field Section CharityEngine Field Required Description
Household Household Household Name Yes  
Household Address Home Address Line 1   Format: requires presence of house number and street name or PO Box
Household Address Home Address Line 2    
Household Address Home Address City   If Address Line 1, requires City, State, Postal Code
Household Address Home Address State   If Address Line 1, requires City, State, Postal Code; Format - 2 Alpha Value
Household Address Home Address Postal Code   If Address Line 1, requires City, State, Postal Code; Zip + 4 required for support of applications such as Advocacy and identification of County; please ensure leading 0 is present where appropriate (i.e. 01104)
Household Address Home Address Country   Assume US if null
Household Communication Preferences Home Landline Receive Calls   Yes, No or null
Household Communication Preferences Home Mobile Receive SMS   Yes, No or null
Household Communication Elements Home Email Address   Format: requires presence of @ and ".xxx"
Household Communication Elements Home Mobile   Format expects 10-digit input; can be 210-555-1234, (210)555-1234, 2105551234
Household Communication Elements Home Mobile Is Preferred Voice   1 (for Yes), 0 (for No), or null
Household Communication Elements Home Landline   Format expects 10-digit input; can be 210-555-1234, (210)555-1234, 2105551234
Household Communication Elements Home Landline Is Preferred Voice   1 (for Yes), 0 (for No), or null
Household Head of Household Head of Household Id   Format: CharityEngine person  Id is expected value
Household Spouse Spouse Id   Format: CharityEngine person  Id is expected value

 

Click Here to Download a Contact-Household (no external id) Import Template:
Image result for excel icon

Click Here to Download a Contact-Household (WITH an external id) Import Template:

Important: Please see Instructions: Importing New Contacts with an External ID section to configure the External ID Type value. Use this value for any contact with an external ID required for import. This value should be used within field "Sync External Type Id"

Image result for excel icon   

Instructions: Importing New Contacts with an External ID

If you are importing contacts which contain a unique identifier from a prior CRM or database, please follow these steps to configure an external id import. This step is critical if the historical id is important to reference on the contact record and/or if this id is used to associate historical transactions based upon this unique value. 

Step 1: Navigate to the Configuration App > Contacts > External ID Types > Create New

Step 2: Create a Name (required) - this is an internal reference . Select Class. Select your CRM/Database from the dropdown menu, or select Other. 

Step 3: Click SAVE to secure your changes.

Step 4: Navigate back to the listing screen to locate the new External Id Types. This value will be used in the Contact-Organization Import WITH External ID. This value should be used with CharityEngine field: Sync External Type Id

Instructions: How to Import Contact Records

Now that you have cleansed your data, added your external synch ID (if applicable), and added your contacts to the import template, you are ready to begin importing. CharityEngine recommends importing a small sample to begin. This allows the user to QA and verify the data has imported as expected. 

The user can choose to leverage the Import (new) or Import (classic). Classic workflow guides end user to map fields manually and then import the source file. Alternatively, new import flow guides end user to upload source file and then user will be guided to map based upon the column headers.

Importing with Import (new)

Step 1: Prepare your Excel file for import, entering one contact record per line. Once complete, save to your local drive. 
Note: when saving the file, ensure you save it as a Tab Delimited (Excel) file to match the file type in CharityEngine.


 
Step 2: To import contacts, navigate to the Workflow & Automation App > Import/ Export. Click on Create New and select Import (new).




Step 3: Select from the drop-down where the file will be imported to, for People Contacts, you want to import to Households. Click NEXT to proceed.
Note: You can also import to organizations or people if that is the contact type. Like contacts should be imported together – households with households, organizations with organizations, people with people.  


    Step 4: Upload your import file noting that any change to File Type should be adjusted prior to import. Click next to proceed.
    Note: If your file does not contain a header row, then adjust Import First Row to yes. This will instruct the importer to import the values in the first row


    Step 5: Begin your data mapping for all columns in your source file. Click next once complete. 
        1. Leverage Existing Template to locate any prior templates for faster mapping
        2. MAP FILE COLUMNS:
          1. Use the drop down from each column to select the appropriate field selection for mapping
          2. Select IGNORE if you wish to have the importer skip importing/updating the contact record
          3. To save the template for future use, ensure Save Template is toggled to Yes. This will allow you to save time by loading the template instead of adding the fields one by one. This will also be helpful if you plan to import a sample and then complete a full import. Or if using an existing template, adjust Save Changes to adjust for any modifications of column mapping changes that may be needed for future reference.
     

    Step 6: Next, prepare your settings for import. Modify the Name of the import job (optional), Mode: Import Data (preset), Start if you wish to schedule in the future (optional). Click next to proceed. 
          1. NOTE - BULK ATTRIBUTION: On this step you can also bulk append a Group, Tag, and/or Opt In List to all contacts being created/updated.  
          2. NOTE - CONTACT MATCHING: If your data is unique and will not create duplicate, no change is needed for Contact Matching and recommend maintaining as Contact Matching is disabled. IF your data has potential duplicates, enable Contact Matching.
          3. NOTE: If you select to enable Contact Matching, the following selections are required:
            1. Multi-Matching Action:
              1. Select Closest Match: Selects the contact that most closely matches the information provided. 
              2. Create New Contact: Ignores the matches and creates a new record with the information provided. 
              3. Fail as Bad Record: Fails this row of the import as a Bad Record.

            2. Match Update Action:
              1. Determines what will happen when a contact match is found - note: does not apply to ID-Based update operations
              2. None
              3. Update

      For more information on the contact matching feature, visit Data Importing: Contacts & Use of Contact Matching
      LOGGING & VALIDATION:
          1. Selection of the Store Import Results can be used (and is required) if the user requires the ability to view diagnostic results and/or to backout changes. Please note this will cause data jobs to run slower and not recommended for large import.


      Step 7: Review and Confirm your import configuration. Click PROCESS to initiate your job. Click OK to confirm.


      Step 8: An success page will be displayed allowing you to View Job Status, Setup Recurring Schedule (for this import), or Import More Stuff. 
      By clicking View Job Status, you will be able to monitor the import. CharityEngine will show you if the import has finished or still processing, if it was successful or if it was a bad record, how many contacts were imported, if any contacts matched, and if any contacts were updated.

      Step 9: Navigate to the Contacts App > Organization & People > Contacts and use the quick filters to review and QA your contact import records
      Pro Tip: Use the Advanced Filters > More Filters > Source App: Data Import to locate imported contact records
      Pro Tip: Review the contact record panels for verification of importing. Use the Go To to locate specific panels, use Edit to see additional contact information, hover over external IDs to view external id (if applicable)

      Importing with Import (classic)

      Step 1: To import contacts, navigate to the Workflow & Automation App > Import/ Export. Click on Create New and select Import (classic).




      Step 2: Select from the drop-down where the file will be imported to, for Organization Contacts, you want to import to Households. Click NEXT to proceed.
      Note: You can also import to people or households if that is the contact type. Like contacts should be imported together – households with households, organizations with organizations, people with people.  




        Step 3: Add field sections for the import file. The fields will be dependent on the data in the file. Click Add Fields and a drop-down will appear for the field selection. 
        NOTE: If you are using the template provided above, using the Add Fields, select each field in the exact order as presented in the Excel import template. 


        Step 4: Click on the field name to Add Field
          • Your fields will appear as you select them. Use the arrows to reorder the fields and use the delete button to easily remove the field from the template.




        Note: If you have a template saved, click Load Template to use a pre-existing template.
        To save the template for future use, ensure you check the box. This will allow you to save time by loading the template instead of adding the fields one by one. This will also be helpful if you plan to import a sample and then complete a full import. 

        Step 5: Once you have selected your data elements for your import, you can click on download import template to begin migrating your data to the import template. This action will create an Excel document where you can enter your contact information. If you have downloaded a template from above, you can save your file to your local network and proceed to Step 7. 


        Step 6: Prepare your Excel file for import, entering one contact record per line. Once complete, save to your local drive. 
        Note: when saving the file, ensure you save it as a Tab Delimited (Excel) file to match the file type in CharityEngine.




        Step 7: Once your import file is prepared, proceed by clicking NEXT
        Step 8: Click on Upload a File
        Step 9: Click on Select File: Choose File and browse your computer for the document you created above


        Step 10: Once appended, the user will receive a Success notification. Click NEXT to proceed.
        Note: If there are any issues w the file appending process, a red bar will appear with additional guidance. Typically an error will appear due to:
          1. The fields selected in Data Jobs picker do not match the field counts of the import template
          2. A row/rows contain data but do not contain an import header


        Step 11: Once the file has been uploaded, you will have the ability to name, add a description. Once complete click NEXT.
          1. NOTE - CONTACT MATCHING: If your data is unique and will not create duplicate, no change is needed for Contact Matching and recommend maintaining as Contact Matching is disabled. IF your data has potential duplicates, enable Contact Matching. 
          2. NOTE: If you select to enable Contact Matching, the following selections are required:

            1. Multi-Matching Action:
              1. Select Closest Match: Selects the contact that most closely matches the information provided. 
              2. Create New Contact: Ignores the matches and creates a new record with the information provided. 
              3. Fail as Bad Record: Fails this row of the import as a Bad Record.

            2. Match Update Action:
              1. Determines what will happen when a contact match is found - note: does not apply to ID-Based update operations
              2. None
              3. Update

        For more information on the contact matching feature, visit Data Importing: Contacts & Use of Contact Matching
        From OTHER SETTINGS:
            1. Selection of the Store Import Results can be used (and is required) if the user requires the ability to view diagnostic results and/or to backout changes. Please note this will cause data jobs to run slower and not recommended for large import.


        Step 12: Confirm your job settings and click FINISH to start your Data job import.



        Step 13: A pop-up will appear that will prompt you to View the Job Status, Schedule Job, or Import More Data.

        By clicking View Job Status, you will be able to monitor the import. CharityEngine will show you if the import has finished or still processing, if it was successful or if it was a bad record, how many contacts were imported, if any contacts matched, and if any contacts were updated.

        Step 14: Navigate to the Contacts App > Organization & People > Contacts and use the quick filters to review and QA your contact import records
        Pro Tip: Use the Advanced Filters > More Filters > Source App: Data Import to locate imported contact records
        Pro Tip: Review the contact record panels for verification of importing. Use the Go To to locate specific panels, use Edit to see additional contact information, hover over external IDs to view external id (if applicable)

        Instructions: How to Evaluate Bad Records

        If you import a contact and a field is missing, for example, you have selected first name in the field selection, but the file you imported does not contain a first name, it will be a bad record and your contact will not import.



        By clicking the number next to Bad, you will be able to see the file error. This will appear in a NotePad pop-up advising you what error was made. once you have found the error, you will be able to fix your file and try to import again.

        Instructions: Additional Contact Import Elements

        If you elect to import additional fields for household record creation, below are a few most frequently used elements. 

        Table Import Field Section CharityEngine Field Required Description
        Household Name Household Name Yes  
        Attribution Group   Each record can have 1 or more groups - Format requirement must include the following presence of a name followed by "space comma space" before the next group name: Group Name 1 , Group Name 2 , Group Name 3
        Attribution Tags   Each record can have 1 or more Tags - Format requirement must include the following presence of a name followed by "space comma space" before the next Tag name: Tag Name 1 , Tag Name 2 , Tag Name 3
        Attribution Opt-In Lists    Each record can have 1 or more Opt-In List Names; this is designed to capture existing email lists currently used by the transitioning organization

        FAQs & Other Recommended Readings

        Q. I would like to assign my contacts to an opt in list during the importing process. Is this possible?
        A. Yes - you can leverage the importing tool in order to apply an opt-in list (or group/tag) assignment during the importing process. See our article on how to bulk assign an opt-in list and reference step 7. 

        Q. I have duplicate contact records. What are the next steps for data cleansing once a contact record has been imported?
        A. Through CharityEngine's contact matching feature, users have several options for managing the review, merging, or deletion of duplicate records. See our article Workflow & Automation: Data Governance – Contact Management (Merge, Delete, Inactive)

        Q. I need to import Contact - People. What resources are available for support?
        A. Please see our article Data Importing: How to Import Contact - People Data

        Q. I need to import Contact - Organizations. What resources are available for support?
        A. Please see our article Data Importing: How to Import Contact - Organization Data

        Q. I need to import Transactions. What resources are available for support?
        A. Please see our article Data Importing: How to Import Transactions

        Q. I would like to learn more about how to use and manage households within CharityEngine.
        A. Please see our article Contacts: How to Create and Manage Household Contact Records



        Related Articles

        Powered by Powered By CharityEngine