Business Logic

• Leveraged Functionality
• Process Overview
  • Lead Creation
  • Lead Update
  • Storing Values From Existing Leads
  • Campaign Member Creation for Lead Only
  • Campaign Member Update for Lead Only
  • Lead Conversion
  • Contact Creation
  • Contact Update
  • Lead to Interaction Mappings
  • Opportunity Creation
  • Opportunity Update
  • Affiliation Creation
  • Affiliation Update
  • Campaign Member Creation or Update

Data is recorded on the Interaction record and used to act on any related records. Entry of a new Interaction may result in all the following depending on the data saved on the Interaction record or found on existing records:

• Lead creation or update
• Campaign Member creation or update
• Lead conversion
• Contact creation or update
• Account creation (for created Contacts)
• Lead to Interaction field updates
• Opportunity creation or update
• Affiliation creation or update

When an Interaction is saved at a "New" status, an Apex process runs. It begins by creating or updating a Lead. If the Campaign or Additional Campaign fields are populated and the “Lead Only” checkbox is checked, up to two Campaign Members may be created or updated and associated to the Lead at this time. The process ends here if the "Lead Only" checkbox is checked. This may be used to import or create records for individuals who are part of the recruitment process, but have not yet raised their hands according to the university's business processes.

The Lead Only process does not query for Contacts. If a Contact with the same name and email or other matching information is in the system, the Lead will still be created. Users should search Salesforce for a matching Contact before checking the “Lead Only” checkbox when manually creating an Interaction. If you are loading a list of records as Lead Only and you want to merge those into existing Contacts, you will need to complete discovery before or after the list load to find matching Contacts and resolve those.

If the "Lead Only" checkbox is not checked, the Apex process uses native Lead conversion to create or update a Contact and Account. The Account created for the Contact is set to the Administrative Account Record Type used by HEDA. Fields may be mapped from an existing Lead to the converted or updated Contact at this time. If academic interest information is provided, an Opportunity is created or updated as well. If the Campaign or Additional Campaign fields are populated, up to two Campaign Members are created and associated to the Contact. One Affiliation may be created or updated and associated to the Contact, and if Primary Affiliation is checked, a HEDA trigger will set the appropriate Primary Affiliation lookup field on Contact.

Here is an overview of this process:

Leveraged Functionality

The Interactions process leverages existing functionality when possible for improved efficiency, maintenance, and scalability. The code relies on standard Salesforce functionality as well as functionality provided through HEDA. The Interactions code relies on standard Salesforce functionality for the following steps:

1. Avoiding the creation of a duplicate Lead using Duplicate Management (see Lead Creation and Lead Update)
2. Avoiding the creation of a duplicate Contact using Duplicate Management (see Lead Conversion, Contact Creation, and Contact Update)
3. Converting a Lead into a Contact, Account, and Opportunity (See Lead Conversion)
4. Moving Campaign Members and Activities to the Contact during Lead conversion (See Lead Conversion)
5. Merging duplicate Lead and Contact Campaign Member records during Lead conversion (See Lead Conversion)
6. Avoiding the creation of a duplicate Opportunity using a unique external ID field (see Opportunity Creation and Opportunity Update)

The Interactions code relies on HEDA functionality for the following steps:

1. Using the Administrative Account Record Type to set the Account during Lead conversion (see Lead Conversion). The HEDA trigger is not used for this, but the code sets the Account to this HEDA record type.
2. Updating the appropriate Primary Affiliation field on Contact depending on the type of Affiliation created. (See Affiliation Creation)

Process Overview

The following sections summarize the steps of the process in the order in which they occur.

Lead Creation

The Interaction process always starts by creating or updating a Lead. If the "Lead Only" checkbox is set to true, the process will not attempt to convert the Lead into a new or existing Contact. This may be used to import purchase lists, update information about individuals who have not yet raised their hands, etc.

The Apex process leverages native Salesforce Duplicate Management to update any existing Leads rather than create new ones. For more information about the basic matching and duplicate rule functionality, review Salesforce’s Managing Duplicate Records in Salesforce resource.

If the Interaction data does not trigger the Lead Duplicate rule based on the Lead Matching rule, the new Lead will be saved with data from the Interaction record, based on the Interaction Mapping records. The process then sets the Lead lookup field on the Interaction record to the created Lead using the Salesforce ID.

Lead Update

If the Lead Duplicate rule is triggered because of a match based on the Lead Matching rule, the code uses the Salesforce ID for the existing Lead provided by the error to update that Lead rather than create a new one. The Lead will be updated with data from the Interaction record based on the Interaction Mapping records. The process then sets the Lead lookup field on the Interaction record to the existing Lead using the Salesforce ID.

Storing Values From Existing Leads

If the process found an existing Lead, it checks if there are any Interaction Mapping records in the system with a Source Object of “Lead” and Target Object of “Interaction.” If there are, the values from the Lead for those mapped fields are captured and stored until after Lead Conversion. See Lead to Interaction Mappings.

Campaign Member Creation for Lead Only

If “Lead Only” is checked and the Campaign or Additional Campaign lookup fields are populated on the Interaction along with the Campaign Member Status or Additional Campaign Status, the code attempts to create Campaign Members for each of the campaigns associated to the new or updated Lead. The Campaign Member records are created with an Upsert Key that must be unique and an error will be returned if the process attempts to create a Campaign Member record with an Upsert Key that already exists. If no error is returned, the record will be saved. The Campaign Member Status selected must match a Campaign Member Status set up on the Campaign selected. If not, the Campaign Member will be created with the default status assigned to that Campaign.

Campaign Member Update for Lead Only

If the system returns any errors because the Upsert Key for a Campaign Member is not unique, the process uses the Salesforce ID found in the error messages to update the existing records rather than create new ones.

Lead Conversion

If an Interaction indicates a Contact should be created or edited (Lead Only checkbox = false), the process attempts to convert the Lead into a new Contact. If the Contact Duplicate Rule is not triggered by the creation of this Contact, the record will save (see Contact creation section below). Otherwise, the Lead will be converted into an existing Contact (see Contact Update section below).

The code leverages the standard Lead conversion process, which creates a Contact and Account, as well as an Opportunity if desired. The Account Name is set using the Company field on Lead, which should be mapped from the Last Name provided on the Interaction. The Account Record Type is set to the HEDA Administrative record type. The conversion process uses the Lead Mappings to update standard fields such as Email, Phone, Lead Source, etc., by default. The Lead Mappings must be set for custom fields included in the package (see the Interaction Mapping section in this document). The standard conversion process also includes moving any standard related records to the Contact record, such as Open Activities, Closed Activities, and Campaign Members. If a Lead is converted into a Contact and both the Lead and Contact have a Campaign Member record for the same Campaign, the system will automatically merge the Lead’s Campaign Member record into the existing Campaign Member record. This is standard functionality and not a customization provided by Interactions for Student Recruitment.

One of the Lead fields included in the package is the Primary Institution lookup field. This allows a university to track the Educational Institution associated to the Lead when loading purchase lists and adding individuals as Leads because they have not raised their hands. However, the Interaction process only creates an Affiliation based on the Affiliated Account field on Interaction during the Contact Creation or Contact Update steps.

Although Primary Institution is a useful field for Leads, and is leveraged to prepopulate the Interaction Action on Lead, the Primary Institution on Lead should not be mapped to the Primary Educational Institution on Contact using either the standard Lead Mappings or an Interaction Mapping record. Review the following hypothetical situation to understand how mapping this field could result in conflicting data:

1. A Lead exists in the system with Washington High listed in the Primary Institution field.
2. An Interaction is created for the same individual with Lincoln High listed in the Affiliated Account field and the Primary Affiliation checkbox set to True.
3. The Interaction is saved and the process runs.
4. The process identifies the existing Lead, updates, and converts it to a Contact. Either the standard Lead mappings or an Interaction Mapping sets the Primary Educational Institution field on Contact to Washington High.
5. A HEDA trigger creates an Affiliation record connecting the Contact to Washington High with the Primary checkbox set to true based on the change to this Contact field (this is a standard HEDA process).
6. The Interaction process updates the other Contact fields, then creates an Affiliation connecting the Contact to Lincoln High with the Primary checkbox set to true.
7. The creation of an Affiliation record with Primary set to true would normally kick off another standard HEDA trigger that would update the Primary Educational Institution field on Contact and uncheck the existing primary Educational Institution Affiliation. However, because the Primary Educational Institution has already been updated once in this transaction (see step 4), the HEDA trigger does not run.
8. You are left with a Contact that has Washington High listed in the Primary Educational Institution field and two Affiliations marked as primary: one for Washington High, and one for Lincoln High.

A university has several options for addressing this situation:

• Consider it an outlier based on the data, map to the Primary Educational Institution field on Contact anyway, and create a report that would identify records with this issue so they can be manually fixed.
• Write a custom Apex Trigger to create an Affiliation from the Lead field upon conversion and do not map to the Primary Educational Institution field on Contact.
• Do not map to the Primary Educational Institution field on Contact. Use the Primary Institution field on Lead only to prepopulate the Lead Action when manually creating an Interaction. Include the Institution on an any mass uploads to Interactions that need it. This is the design used in this package.

Contact Creation

If the Lead conversion errors because of the Contact Duplicate rule, the process uses the Salesforce ID provided in the error to merge the Lead into the existing Contact instead of creating a new Contact. Any values on the Lead record that are mapped using standard Lead Mapping on the Lead object will be updated on the Contact. After this happens, the process updates any fields on the Contact based on the values on the Interaction record using the Interaction Mappings. The process then sets the Contact lookup field on the Interaction record to the existing Contact using the Salesforce ID.

Contact Update

If the Lead conversion errors because of the Contact Duplicate rule, the process uses the Salesforce ID provided in the error to merge the Lead into the existing Contact instead of creating a new Contact. Any values on the Lead record that are mapped using standard Lead Mapping on the Lead object will be updated on the Contact. After this happens, the process updates any fields on the Contact based on the values on the Interaction record using the Interaction Mappings. The process then sets the Contact lookup field on the Interaction record to the existing Contact using the Salesforce ID.

Lead to Interaction Mappings

If the process stored values from an existing Lead, those values are written to the Interaction record based on the Interaction Mapping records.

Opportunity Creation

The Interaction Process attempts to create a new Opportunity when there is a value in the Opportunity Key formula field. By default, the Opportunity Key formula field is blank unless there is a value in the Recruitment Interest or Academic Interest field. See Matching with Opportunity Key for detailed information about the Opportunity Key. If the Opportunity Key is blank, the Interaction skips all Opportunity create or update steps. This is helpful when logging data that does not contain reliable or sufficient recruitment information.

If the Opportunity Key on the Interaction matches an existing Opportunity, Salesforce returns an error and the existing Opportunity is updated.

If no Opportunity with this Opportunity Key exists in Salesforce, the record saves with data from the Interaction based on the Interaction Mapping records. The process then sets the Opportunity lookup field on the Interaction record to the created Opportunity using the Salesforce ID.

Opportunity Update

If the process attempts to create an Opportunity with the same Opportunity Key as a record that exists in Salesforce, the system returns an error, which includes the Salesforce ID of the existing Opportunity. The process then updates this existing Opportunity with data from the Interaction record based on the Interaction Mapping records instead of creating a new record. The process then sets the Opportunity lookup field on the Interaction record to the updated Opportunity using the Salesforce ID.

Affiliation Creation

The Affiliation Key is a formula field on Interaction that represents a unique value leveraged in the Affiliation creation process, similar to Opportunity creation. By default, it is set using the following formula, which ensures only one Affiliation exists per Contact and Account combination:

IF(ISBLANK(TEXT(Affiliation_Account__c)), "", "." + CASESAFEID(Affiliated_Account__r.Id)

If the Affiliated Account lookup field on the Interaction is populated, the process will attempt to create a new Affiliation, setting the Upsert Key to the Salesforce ID of the Contact created or updated earlier plus the Salesforce ID of the Account saved in the Affiliated Account lookup field on Interaction. If no Affiliation with this Upsert Key exists in Salesforce, the record will save with data from the Interaction record based on the Interaction Mapping records.

A workflow rule ensures the Upsert Key field on Affiliation is kept up-to-date in case details on the Affiliation change or an Affiliation is created outside of Interactions. An admin can change the way this Upsert Key works. For example, Role could be added to the formula as an attribute, which would allow multiple Affiliations to exist per Contact and Account combination, as long as they have different Roles. See the Installation and Configuration Guide for more information.

Affiliation Update

If the process attempts to create an Affiliation with the same Upsert Key as a record that exists in Salesforce, the system will return an error including the Salesforce ID of the existing Affiliation. The process will then update this existing Affiliation with data from the Interaction record based on the Interaction Mapping records instead of creating a new record.

Campaign Member Creation or Update

If “Lead Only” is false and one of the Campaign fields is filled out, the same process as described in the Campaign Member Creation for Lead Only or Campaign Member Update for Lead Only section is completed to create or update a Campaign Member, but the records are associated to the new or updated Contact instead of the Lead.