What are platform integrations?

This feature allows institutions to connect their Mainstay data to a third-party platform, such as Salesforce. This enables a 2-way sync of contact record data, including default fields (name, phone, email, etc.) and custom fields created by the partner. To learn more, visit Platform Integrations.

Overview

Mainstay Sync for Salesforce is an unlocked package available for Salesforce admins. This integration provides a number of features:

• One-time Import and Export commands, to generate new Salesforce records for Mainstay Contacts and to generate new Mainstay Contacts from Salesforce records.
• One- or two-direction syncing, to update Mainstay Contacts automatically when a Salesforce record is changed and/or update Salesforce records automatically when an Mainstay Contact is changed; this also includes field mapping customizations and robust error logging.
• Viewing Mainstay Conversations within the Salesforce Contact record page.
• Viewing Mainstay Campaign history within the Salesforce Contact record page.

Installation

1. Salesforce
   1. Log into your Salesforce account at https://login.salesforce.com/.
      1. Ensure "My Domain" is enabled. (See https://help.salesforce.com/articleView?id=sf.domain_name_overview.htm&type=5)
   2. Access the installation manager at https://appexchange.salesforce.com/appxListingDetail?listingId=a0N3A00000FMnUFUA1

      1. To use this package in a Salesforce sandbox, instead of login (https://login.salesforce.com/packaging/installPackage...) use test (https://test.salesforce.com/packaging/installPackage...)

      2. To use this package in a custom "My Domain" URL, go to Setup > Company Settings > My Domain and check the value of the current My Domain URL. Then instead of login.salesforce.com (https://login.salesforce.com/packaging/installPackage...) use your custom My Domain URL (https://schoolname-sandbox.my.salesforce.com/packaging/installPackage...)

   3. Grant permissions as necessary and select "Install."
      • Note that this may take up to 5 minutes; Salesforce will notify you by email when the package has been installed.
2. Mainstay
   
   1. Log into your Mainstay account at https://app.mainstay.com.
   2. In the sidebar, navigate to Settings > Mainstay API.
      • If this option is not available, contact your Partner Success Manager.
   3. In the top-right corner, select "Generate a new token." Enter a name, such as "Salesforce," and then copy the randomly generated integration token.
3. Mainstay Sync for Salesforce integration
   1. When the package has installed, return to Salesforce.
   2. Use the app selector to search for "Mainstay Sync" and open this app. Note that in some older versions, this may say "AdmitHub Sync".
      1. Note that if you installed this "for Admins Only", you may need to ensure the tab visibility is set to "Default On" (https://help.salesforce.com/articleView?id=users_tab_visibility.htm&type=5).
   3. Paste the Mainstay API token into the "API token" field. Click "Connect." This is necessary to send information from Salesforce to Mainstay.
   4. Use the gear icon to access Setup. Navigate to Apps > App Manager > Mainstay Sync (Connected) > rightmost dropdown > View. Again, note that in some older versions, this may be labeled "AdmitHub Sync".
   5. Copy the values from "Consumer Key" and "Consumer Secret" into the respective fields on the Mainstay "Salesforce" page. This is necessary to send information from Mainstay to Salesforce.
   6. Return to the Mainstay Sync for Salesforce page click "Authorize Salesforce for Mainstay".

Customization

SYNC STATUS

In this section, you can independently control the direction of data:

• "Sync Salesforce --> Mainstay": if enabled, any changes you make to Salesforce records will be immediately forwarded to the corresponding Mainstay Contacts, including creating new Contacts.
• "Sync Mainstay --> Salesforce": if enabled, any changes you make to Mainstay Contacts will be immediately forwarded to the corresponding Salesforce records, including creating new records.

Review the Installation section to ensure the necessary authentication keys have been shared between the two platforms.

FIELD MAPPINGS

In this section, you can customize which Salesforce objects are synced, and for each one, which fields and Mainstay Contact Attributes will be mapped. By default, only a few basic fields will be mapped.

1. To add a new Salesforce Object Mapping, click New SObject Mapping and select a standard or custom Salesforce Object.
   • 
2. The Record Sync Criteria indicates which Boolean (true/false) field is used to determine whether a Contact will sync with this Salesforce Object. Note that this can also be a Formula Field that outputs true or false. If this is left blank, then all contact records will be eligible for syncing.
   • 
3. Use the Create Unmatched Records checkbox to determine how to handle incoming contact records from Mainstay who do not already have a corresponding match in Salesforce. (See below for customizing the matching logic.) If this is checked, unmatched records will be created as new records in Salesforce. If this is not checked, then unmatched records will be ignored.
   • 
4. To add a field mapping for this Salesforce object, click New Field Mapping.
   • 
   • Select the Salesforce field from the left column.
   • Select the Mainstay field from the right column. Any custom fields you have created on Mainstay will appear in this list. (See Contact Fields Manager.)
   • Use the Matching checkbox to determine if this field should be considered when looking for existing Salesforce records whenever a new Contact record is sent from Mainstay to Salesforce. At least one field must be set for Matching.
   • Note that some Mainstay fields cannot be overwritten by data from Salesforce, such as the Mainstay ID or the contact's Created At date.
   • Similarly, Salesforce formula fields cannot be overwritten by data from Mainstay, since they are computed from a formula. This allows you to configure read-only fields to send data from Salesforce to Mainstay.
   • Note that the Salesforce ID is automatically mapped to Mainstay's "CRM ID" field.
5. To edit or delete a field mapping, click the dropdown arrow on the right side.
   • 

INITIAL SYNC

In this section, you have the option to batch import and export records. It is recommended that you run this after creating the field mapping. Note that each batch import may take several minutes.

• "Import all Contacts from Mainstay": when clicked, this will attempt to match existing Mainstay Contacts to existing Salesforce records based on the individual's first name, last name, and mobile phone.
  • If it detects a match, the Mainstay Contact will be given a CRM_ID corresponding to the Salesforce record.
  • If it does not detect a match, a new Salesforce record will be created. The Mainstay Contact will then be given a corresponding CRM_ID.
• "Export all Contacts to Mainstay": when clicked, this will attempt to match existing Salesforce records to existing Mainstay Contacts based on the individual's first name, last name, and mobile phone.
  • If it detects a match, the Mainstay Contact will be given a CRM_ID corresponding to the Salesforce record.
  • If it does not detect a match, a new Mainstay Contact will be created, and will be given a corresponding CRM_ID.

Logging

SYNC STATUS

"Latest Sync": This field will indicate the date, time, status, and Salesforce record that was last updated with changes sent to Mainstay.

SYNC RESULTS

Visit this tab to view a history of all Sync Results, including:

• a link to a more detailed view for the individual Sync Result
• a link to the Salesforce record
• a status (Success / Fail)
• if the status is Fail, an explanation

If you encounter data validation errors while importing contact records, visit the Import Error Dictionary to better understand next steps.

Pro tip: You can delete all Sync Logs in the Salesforce Developer Console with the following command:

delete [select id from admithubsync__SyncResult__c]; 

Conversations & Campaigns

It is also possible to view Mainstay Conversations for any given Contact by viewing the corresponding Salesforce record, as well as a list of all Campaigns the Contact received.

1. On Salesforce, click "Setup" in the top menu.
2. In the Quick Find box, search "Lightning App Builder".
3. If you already have a Lightning Page for viewing Contact records, select that. Otherwise, click "New" above the Lightning Pages table and follow the creation wizard:
   1. Select "Record page" from the left sidebar of the "Create a new Lightning page" pop-up.
   2. In the Label field, enter a name, such as "Contact".
   3. In the Object field, enter "Contact".
   4. Select the desired layout.
      • Recommended: CLONE SALESFORCE DEFAULT PAGE > "Contact Grouped View Default"
4. Once in the Lightning App Builder, select the section of the page where you would like to add Mainstay Conversations.
   • Recommended: add a new tab in the Activity / Chatter widget, named "Mainstay Conversations" or "Mainstay Campaigns"
5. On the left side bar of Components, scroll to the bottom and drag the "Mainstay Contact Messages" into your desired section / tab, which should read: "Add component here."
6. Click "Activate" in the top-right corner.
   • Recommended: Assign as Org Default.
7. Navigate to an individual Contact page in any app (such as Sales) and you will now see the Mainstay Conversations and/or Mainstay Campaigns for this record.
   • Conversations: Incoming (student) messages will appear left-aligned.
   • Conversations: Outgoing (bot / campaign) messages will appear right-aligned.
   • Campaigns: Displayed information includes the Script Name, Type, Status, and Time Sent.
     

Troubleshooting

If you are experiencing permissions errors, such as

System.QueryException: Insufficient permissions: secure query included inaccessible field

when using TargetX or similar add-ons, try granting the following permissions:

• SyncResult__c - read, create; edit for all fields

• SyncMapping__c - read; read for all fields

• AppLogs__c - read, create; edit for all fields

• AppLogEvent__e - read, create