Troubleshoot Invalid NPSP Data Import Help Text Mappings (Legacy)

Invalid Object Group API Name

First, it's important to understand Object Groups. Object Groups are slightly different than objects. Object Groups are collections of field mappings that tell the NPSP Data Importer tool what types of records (e.g. Contacts, Opportunities, Payments, etc.) to create or update. NPSP is able to link records within a single row of your import to one another because fields mappings are bundled in Object Groups in this way.

Let's look at the two Contact1 and Contact2 Object Groups as an example. These are linked directly to their Household Accounts. At times, you may want to include two Contacts in a single household. To achieve this, in your import file enter the first Contact in the Contact1 columns and the second Contact in the Contact2 columns. When Contact1 is created, NPSP creates a Household Account for Contact1. Because of the Contact1 and Contact2 Object Mappings, Contact2 is added to Contact1’s Household Account when you import the file.

Help Text mapping only supports the following Object Groups:

• Account1 - Not the Household Account; an Organization Account affiliated with Contact1.

• Account2 - Not the Household Account; an Organization Account affiliated with Contact2.

• Household - The Household Account.

• Contact1 - The primary Contact.

• Contact2 - The other Contact or Contacts in a household.

• Address - The household address.

• Opportunity - Donation fields.

• Payment - Payments related to the Opportunity.

The Object Group component of the Help Text mapping must conform to one of the Object Groups above. Some examples of invalid Object Group mappings:

• Account.Name: Doesn't include which Organization Account the field is on. Specify either Account1 or Account2.

• Acccount1.Name: Account1 is misspelled.

• Account_1.Name: There shouldn't be a space—represented by the underscore—between Account and 1.

• Account3.Name: Help Text mapping only supports Account1 and Account2 Object Groups.

In addition, you can't map to an Object Group that isn’t listed above. Examples of these invalid mappings are:

• npe5__Affiliation__c.Name: You can’t map directly to the NPSP Affiliation object, but if you complete the information for Account1 or Account2 in the import file, NPSP will automatically create an Affiliation between Contact1 and Account1 or Contact2 and Account2.

• Allocation__c.Name: Help Text mapping doesn't support mapping to GAU Allocations on Opportunities. If you convert to Advanced Mapping, GAU Allocation mapping will be set up for you. See Configure NPSP Data Importer for more information.

• npe03__Recurring_Donation__c.Name: You can’t map to the NPSP Recurring Donation object with Help Text mapping, but if you convert to Advanced Mapping, you can set up this custom mapping. Read more in Customize Advanced Mapping.

Invalid Field API Name

The Field API Name needs to match the target field exactly.

This includes the number of underscores, that pesky __c at the end of custom fields, and capitalization. Some specific examples of invalid field API name mappings are:

• Account1.name: Name must be capitalized. This mapping should be Account1.Name.

• Account1.npsp__Matching_Gift_Company: This is almost the full API name, but it’s missing __c on the end that is on every custom field. It should be Account1.npsp__Matching_Gift_Company__c.

• Account1.npsp__MatchingGiftCompany__c: The API name for Matching Gift Company has underscores between the words.

• Account1.MailingCity: This is a tricky one! MailingCity is a valid API name for a field, but Mailing City isn’t a field that exists on the Account object; it’s on the Contact object. The mapping for a city field on the Account object should be either Account1.BillingCity or Account1.ShippingCity.

• Account1.[a field that doesn't exist]: If you’ve not created a field on the target object, you don’t have its API name.

The foolproof way to make sure you’re using the correct API name is to go to the target object, copy the whole API name of the field, and paste it in the FieldName piece of the mapping. Pro tip: open the target object field list in a separate browser window and the create the corresponding NPSP Data Import fields in another window.

Incompatible Data Types

For the most part, when you set up the field on the NPSP Data Importer object, you must select the same field type as the custom field you're mapping to. For example, if the field on the Contact record was a Date field, you'd select Date.

There are two notable exceptions:

• When the target field is a relationship field (lookup or master/detail).

• When the target field is a checkbox.

Relationship fields—lookup or master/detail—must be mapped as Salesforce IDs. This includes the standard Owner field, which is related to the User object. For a relationship field, the NPSP Data Import field should be a Text field of 18 characters to accommodate the 15 or 18 digit Salesforce ID (not the Name) of the related record.

In order to allow more flexibility around checkbox fields, the NPSP Data Import field that will send information to a target checkbox field should be a picklist. This picklist translates what you want to see in the checkbox field (the checkbox as checked or unchecked) to their Boolean equivalents (True for checked and False for unchecked). Through NPSP Data Import, you'll be able to uncheck a previously checked checkbox field or even leave a checkbox field completely unchanged by leaving that cell empty. Read more about mapping Checkbox Fields.

Improperly Named Unique ID Field

The name of the NPSP field is important when you're creating a field that corresponds to a Unique ID field. In order to see any values in the Contact Custom Unique ID or Account Custom Unique ID fields in the Data Importer Configuration options, the field you want to map must be marked as Unique and External ID.

Additionally, for Unique ID fields, you must create two corresponding fields, one for Contact1 and one for Contact2 (or Account1 and Account2) and they must be named properly. The corresponding fields should NOT be marked as Unique and External ID. Read more in Important Information about Unique ID Fields.

Two NPSP Data Import Fields Mapped to Same Target Field

Each NPSP Data Import field should only be mapped to a single target field. If you map two NPSP Data Import fields to the same target field and you have information in both NPSP Data Import fields, the field that processes last will be the value that is imported into the target field.

Probably the most common way this happens is where two different NPSP Data Import fields are created by different users at different times. Let's say you have a field on the Contact object named Preferred Name. Years ago, one of your admins created an NPSP Data Import field named Contact1 Casual Name and used Help Text mapping to send information from Contact1 Casual Name to Preferred Name for Contact1. More recently, a new admin didn't notice the Contact1 Casual Name field and created a new NPSP Data Import field named Contact1 Nickname and also mapped it to Preferred Name.

Here's how this setup goes sideways. Another admin prepping data for an upcoming import sees both Contact1 Casual Name and Contact1 Nickname in the CSV template, and for a supporter named Robert 'The Bobster' Miller, the admin enters Bob in the Contact1 Casual Name column and The Bobster in Contact1 Nickname. When the import is processed, the NPSP Data Import field processed second—let's say Contact1 Nickname, The Bobster—overwrites the Contact1 Casual Name value and the Preferred Name field ends up with The Bobster.

Before you know it, your major gifts officer calls Mr. Miller The Bobster. And that might be ok if Bob's not into the whole brevity thing, but more likely it's a nickname only his closest friends use. So be sure to check your field mappings carefully and completely.