NWDC

home   about   contact   downloads   links   pricing   reading list   [salesforce]   site map  

Current loctn: salesforce > npap v3 upg > sf amc util > amc util index

Salesforce NPSP V3 Upgrade - SF Account Model Conversion Utility Operational Details

This document is authored by Larry Bednar and provides a high-level description of tasks performed by, and prerequisites listed for use of the SalesForce Account Model Conversion utility provided with installation of NPSP V3.

Much of this information was copied from the utility start-up screen in a SF instance with NPSP V3 installed, for easier reference here.

Additional tipslisted towards the end of this document were developed from direct experience using the AMC utility.

[LB - The information presented here (to the best of my knowledge) is accurate as of 2/22/2015. I've received indications that the AMC utility may be updated to edit the description of actions presented on the AMC start page. When that update is completed, this page may require an update to reflect those changes.]

Operational Details/Hints

Only Records Linked to NPSP Households Are Processed

If a Contact is not linked to an NPSP Household record, no related data is created or modified.

For instance, the AMC functions to remove direct links between non-one2one Accounts and to create Affiliation records to instead represent those links only operates in this situation:

  1. Contact is directly linked to an Account that is not a one-2-one Account
  2. Contact is also linked to an NPSP Household record

Legacy One-2-One Accounts Remain in Place

Original links to the one-2-oneContact remain in place on these records. And that linking still uses the Account.npe01_One2OneContact__c field, although the labeling of this field has changed to Primary Contactand the use of this field has changed.

However, earlier NPSP automation that would cascade record deletions to linked Contacts when the Account is deleted is no longer in effect after NPSP V3 installation. So it is possible to delete these Accounts directly without concern about cascading deletes of linked Contacts.

These will need to be deleted after conversion results are confirmed to be acceptable.

I generally mark these records with a revised Account.Name value with suffix text such as OBSOLETE ONE2ONE.

I find queries with these results to provide good identification of these records:

  1. Construct a join of pre-conversion records as follows:

    NPSP Households -> Contacts -> Accounts

    Include the Account.ID value in the query results

  2. Search for records returned by the join which provide the following characteristics:
    1. Account.Name = Contact.Name and Account.npe02_One2OneContact = Contact.Id
    2. check for any remaining links of these Accounts to Opportunities

      An aggregate statistic like the count of linked Opportunities works well for this purpose

      The presence of remaining links to Opportunities probably indicates that the AMC did not complete the handling of those NPSP Households

    3. The same join result used to update the Account.Name values can be used to delete the same records later using Apex Data Loader, etc.

The query description provided here still needs a little work to ensure that unconverted NPSP Households having no member opportunities linked are renamed or not renamed appropriately.

Legacy NPSP Household records Remain in Place

Original NPSP Household -> Contact links remain in place, but deletion of these NPSP Household records does not cascade to linked Contacts

Might be wise to retain these during validation activities used to confirm NPSP V3 data processing results, then delete these records later.

Newly Created HouseholdAccounts Designate The User Who Ran the AMC as Owner

If the newly created household Accounts need to have ownership set the same as the original legacy NPSP Household records from which they are created:

  1. Create an Account field to hold Salesforce ID of legacy NPSP Household record from which the new Account record is derived

    I typically use an Account field named NPSP_Household_Id__c

  2. Configure the AMC utility to make use of this field during operation to store the Salesforce ID of the source NPSP Household record.
  3. Extract Account records with values in the NPSP_Household_ID__c field, manipulate data in order to transfer Owner value from legacy Household record to the newly created householdAccount record

The AMC Utility Does NOT Display the Sandbox Indicator When Running

As of 12/15/2014, I found that when the AMC utility is running in a sandbox, it does not display the Sandbox marker that is otherwise displayed at the upper right corner of the Salesforce user interface.

Do not freak outabout this. (I did so the _first_ time I ran the AMC!) Just make sure you're starting the utility within a sandbox and trust your location as the AMC utility runs.

All Accounts, Contacts, Opportunities, Tasks Must Designate Active Users as Owners

Although it seems logical that only records re-parented by the AMC would need activeowners, the AMC actually requires that all records in objects it works with have activeowners before it will proceed.

A Power of Us Hub discussion initiated by Michael Smith around 12/14-15/2014 reveals this.

The Power of Us Hub question is I'm hearing that to run the Household Converter Utility, it's necessary to change the owner on all Activity Records to an active owner. Is this true?

URL:https://powerofus.force.com/0D58000001hsv3r

(Be aware, you'll have to read _several_ comments downward in that Power of Us Question before you reach the conclusions that all Tasks must be linked to active owners. And you'll have to read still further for the clear input about Accounts, Contacts, Opportunities.)

The AMC will not run if _any_ records in these objects have inactive owners designated.

Run Time

Recent examples of AMC runs:

Example A (Pesticide Action Network of North America)

  1. sandbox
  2. about 700 Mb of data
  3. about 25,000 householdaccounts created
  4. about 40,000 Opportunities relinked to new householdAccounts
  5. 70 minutes required for completion

Opportunity Contact Roles Must Be Set Correctly Before AMC Utility is Run

It is desirable to address problems with Opportunity Contact Role settings before the AMC utility is run.

  1. Situations where an Opportunity is linked to more than one OppContactRole designated as IsPrimary = 'true' will be detected as errorsby the AMC utility.

    This is true even if the _multiple_ IsPrimary OppContactRoles present link to the same Contact.

    The AMC utility will stop execution when these situations are encountered. And because the AMC utility processes NPSP Household records in batches of 200, even the presence of just one Opportunity record of this type can potentially prevent conversion of many NPSP Household records, and even more Opportunity records

  2. Situations where an Opportunity is marked with no Contact Role marked as IsPrimary = true will result in these records not being relinked to a new household Account created by the AMC utility.

    Every Opportunity for which relinking to a newly created household Account is desired must have a Contact Role indicating IsPrimary = true in order for the AMC utility to relink the Opportunity to a newly created household Account record.

Some additional detail about these situations is provided below.

Problems When Opportunities Have Multiple Primary OpportunityContactRole Records

Some users have reported incomplete results from the use of the AMC utility in situations where multiple OpportunityContactRole records with IsPrimary = true are linked to an Opportunity. Larry Bednar has encountered this directly during uses of the AMC utility.

See Power of Us Hub question: Recovering from serious errors in conversion>

URL is https://powerofus.force.com/0D58000001gs3bY

The AMC issues an error message like duplicate id: {opp id value} providing the ID of the _first_ Opportunity where this sort of situation was encountered.

The number of NPSP Household records that are rejected for conversion can be much larger than the number of problem Opportunities:

  1. The AMC processes batches of 200 NPSP Households at a time
  2. If any Opportunity linked to Contacts in any of these NPSP Households has multiple IsPrimary OpportunityContactRoles linked, the entire batch of 200 NPSP Households is not converted

Theoretically, 7 problem Opportunities could block the conversion of 7 x 200 = 1400 NPSP Households. And of course, there might be several thousand linked Opportunities that should have been relinked to new household Accounts... but were not.

Opportunities Not Relinked to New Household Accounts When Opportunities Have No Primary OpportunityContactRoles

In a situation where:

  1. A member of an NPSP Household is linked to a one-2-one Account
  2. Opportunities exist which are:
    1. Linked to the one-2-one Account
    2. Are not linked to the household member's Contact record with primary OpportunityContactRoles

The results of an AMC run will be:

  1. A new household Account record
  2. The Contact record for the NPSP Household member will be directly linked to the new household Account
  3. Opportunities that were linked to the Contact with primary OpportunityContactRoles will be re-linked as expected to the new household Account
  4. Opportunities that were not linked to the Contact with primary OpportunityContactRoles will still be linked to the original one-2-one Account

Before running the AMC, it may be wise to create primary OpportunityContactRole records as needed to ensure that Opportunities from one-2-one Contacts in NPSP Households are always re-parented to newly created household Accounts.

Errors With Contacts Having No Directly Linked Account

Some users have reported incomplete results from the AMC utility in situations where Contacts linked to an NPSP Household is not directly linked to any Account.

The error arises during the portion of AMC operation where the utility is attempting to disconnect Contacts from a previously linked non-one2one Account, to create NPSP Affiliation records representing the same association. The effort to create Affiliations fails because an Account lookup is required on NPSP Affiliation records.

Note: A leverage similar to that mentioned above regarding Opportunities with multiple IsPrimary OpportunityContactRoles applies here. The AMC processes batches of 200 NPSP Household records at one time. A problem with a single one-2-one Account might throw an error that would typically stop the conversion of 200 NPSP Households and all related data.

Repeat Uses of the AMC Utility

Several users have reported incomplete results from use of the AMC utility. (See Power of Us Hub question Conversion utility tool did not change all of my clients 1:1 contacts with households into Household Accounts. What if any ramifications are there if I run the tool again for the remaining contacts?)

Note the warning on the NPSP AMC start page that indicates

...This converter will attempt to ignore any Contacts that already have a Household Account associated.

This implies that the AMC can be rerun without an effort to reverse results of a _previous_ run if an earlier run left some NPSP Household record unrepresented by newly create Account records with record type Household Account. Kevin Bromer of Salesforce has confirmed this in Power of Us Hub responses. And several users have reported running the AMC as many as 8 times in a single conversion project without any problem duplicates of household Accounts resulting.

Valid XHTML 1.0 Strict Last modified: 10:29:53 12-Mar-2015