Learn about our newest features and enhancements!
Data Importing: How to Import Contact - People Data
Authored by:
on 3/10/2024 5:27:00 PM

Introduction

You may identify the need to import People contacts to your CharityEngine instance. This can include adding new contacts from an event, adding email address, converting from other systems, etc. Adding contacts, and other data elements, can be accomplished through the Workflow & Automation Importer tool.


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 People records the minimum required fields will include First Name and Last Name; if your data does not contain First Name and/or Last 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. 

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 first name AND last name value (First Name and Last Name are both required as the minimum field for importing to Contact-People 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
  1.  
    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)
Step 2: Leverage Excel 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 
  1.  
    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 first name and/or last name field 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 people, preparation is an important activity to ensure you have clean data for your CharityEngine database. When importing People for your contact records, the minimum requirement is First Name and Last Name

The following table will provide you with basic people 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 Data Type
Description
People Name First Name Yes Alphanumeric
 
People Name Last Name Yes Alphanumeric  
People Name Name Prefix   Alphanumeric  See Configuration App > Contacts > Prefixes to add unique prefix needs prior to import
People Name Name Suffix   Alphanumeric See Configuration App > Contacts > Suffixes to add unique prefix needs prior to import
People Address Home Address Line 1   Alphanumeric Format: requires presence of house number and street name or PO Box
People Address Home Address Line 2   Alphanumeric  
People Address Home Address City   Alphanumeric If Address Line 1, requires City, State, Postal Code
People Address Home Address State   Alphanumeric If Address Line 1, requires City, State, Postal Code; Format - 2 Alpha Value
People Address Home Address Postal Code   Alphanumeric 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)
People Address Home Address Country   Alphanumeric Assume US if null
People Communication Preferences Receive Mail   Numeric 1 (for Yes), 0 (for No)
People Communication Preferences Receive Phone Calls   Numeric 1 (for Yes), 0 (for No)
People Communication Preferences Receive SMS   Numeric 1 (for Yes), 0 (for No)
People Communication Preferences Receive Email   Numeric 1 (for Yes), 0 (for No)
People Communication Elements Home Email Address   Alphanumeric
Format: requires presence of @ and ".xxx"
People Communication Elements Home Mobile   Numeric
Format expects 10-digit input; can be 210-555-1234, (210)555-1234, 2105551234
People Communication Elements Home Mobile Is Preferred Voice   Numeric 1 (for Yes), 0 (for No)
People Communication Elements Home Mobile Receive SMS   Numeric 1 (for Yes), 0 (for No)
People Communication Elements Home Landline   Numeric
Format expects 10-digit input; can be 210-555-1234, (210)555-1234, 2105551234
People Communication Elements Home Landline Is Preferred Voice   Numeric
1 (for Yes), 0 (for No)
People Attribution Gender   Numeric
Format: 0 (for Male), 1 (for Female), or null
People Attribution Birth Date   Numeric
Format: MM/DD/YYYY or YYYY/MM/DD
People Attribution Marital Status   Alpha
Format: Single, Married, Widowed, Divorced, Separated, Null
People Attribution Deceased   Alpha
Format: Yes, No, or null

 

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

Click Here to Download a Contact-People (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-People 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 People. Click NEXT to proceed.
Note: You can also import to organizations or households 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 People Contacts, you want to import to People. Click NEXT to proceed.
      Note: You can also import to organizations or households if that is the contact type. Like contacts should be imported together – households with households, organizations with organizations, people with people.  
        • Note: If you wish to automatically assign all contacts to a Group, Tag, or Opt-In List assignment, click on the arrow to expose the available options and assign
        • See our article on how to bulk assign an opt-in list and reference step 7. 




      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 people record creation, below are a few most frequently used elements. 

      Table Import Field Section CharityEngine Field Required Data Type
      Description
      People Name First Name Yes Alphanumeric  
      People Name Last Name Yes Alphanumeric  
      People Attribution Group   Alphanumeric
      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
      People Attribution Tags   Alphanumeric 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
      People Attribution Opt-In Lists    Alphanumeric 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
      People Employer Linked Employer Id   Numeric
      Use this field if the organization already has a CharityEngine ID
      People Employer Linked Employer Name   Alphanumeric Use this field if the organization does not already have a CharityEngine ID. Use of this field will create an Organization record with a new CharityEngine ID


      FAQs & Other Recommended Readings

      Q. I imported a list of contacts and they are all opted out of communications, why did this happen and what can I do to opt them in. 
      A. By Default, any contact added to the database will be opted out of communication unless stated otherwise. This is in order to follow compliance standards around marketing communication. You can add communication preference fields to your import such as Receive Email or Receive Mail to your import file to opt them in to those methods.

      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 above. 

      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 - 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 Contact - Household. What resources are available for support?
      A. Please see our article Data Importing: How to Import Contact - Household Data

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



      Related Articles

      Powered by Powered By CharityEngine