The Fonteva integration with Higher Logic Thrive Community (Thrive Community) requires a valid connection to Salesforce's Partner API (SOAP). Every member refresh involves constructing a database query using Salesforce's own database language, SOQL. The query is then sent to the API returning all the relevant information.
Every Higher Logic user comes from the Contact object; while every organization user comes from the Account object. These two objects will include the group memberships using various relationship objects previously configured from the Fonteva package.
The periodic refresh service constructs a SOQL query that looks at a custom field that Higher Logic will create on the Contact and (if applicable) Account objects called "HL Mod Date". This datetime field will be populated with a value within Salesforce if this individual user or organization user requires a refresh on the Higher logic side. This field is populated via a custom Flow (also created by Higher Logic) that must be installed in Salesforce for each HL Mod Date field. All Salesforce integrations will sync Contacts as user records on our end, requiring an HL Mod Date field and corresponding Flow to update that HL Mod Date field on the Contact object. If the integration is syncing company records (Account object in Salesforce), a second HL Mod Date field and second Flow (to update that Account HL Mod Date field) must be installed on the Account object.
For Fonteva, an additional custom field and accompanying Flow must be created for each Fonteva object configured to come over. For example, if badge-based groups were to come over, a Badge Flow and a custom field on the Badges object are required.
To learn more about Flows and custom fields and how they look like within Salesforce, see the Salesforce Integration Guide. Note that these instructions are not necessary to complete the integration, as Higher Logic will create the Flows during implementation..
The Salesforce API is throttled, meaning there is a limit to the number of API calls for any service hitting the API every 24 hours. If the limit is hit within the 24 hour window, any use of the API will result in an error for any service. To counteract this, Higher Logic has implemented an API limit checker. Any request that exceeds a threshold percentage of total API calls created by Higher Logic will be queued for the next day.
Data refreshes
The integration uses three types of refresh to synchronize data in Fonteva with the associated records in Higher Logic to ensure that is as up-to-date as possible.
- Member Refresh - updates user-related information, including group memberships. Think of this as a "pull" for data.
- Periodic Refresh - detects any users that have updated their information since the latest Periodic Refresh. This refresh acts as an ongoing sync for Higher Logic to align its records with the data in the Fonteva database.
- Meeting Refresh - updates all meetings and calendar events in Higher Logic. This usually gets set on a daily schedule.
NOTE: Higher Logic is taking a snapshot of your database every 30 minutes (the Periodic Refresh) so some user updates might be missed. If any issues come up with the Periodic Refresh, escalation with the parent system may be required.
Refreshes & API calls
Below are the API calls that each refresh type uses and how often; these are estimates only.
- The Periodic Refresh uses 1 API call every 30 minutes.
- The Member Refresh uses 1 API call per refresh.
- The Meeting Refresh uses 1 API call every day.
EXAMPLE: Assume that a Periodic Refresh returns five users that need to be updated in Higher Logic. The Member Refresh has to run for each user to be updated. The Periodic Refresh API call plus the five Member Refresh API calls totals six API calls.
Troubleshooting
If you experience a situation in which a change to a Contact record is not being picked up by the Periodic Refresh and updated in Higher Logic, make sure that the:
- Periodic Refresh is on
- HL Mod Date field(s) has been installed
- Flow has been created and activated, and the field is included in the Flow's logic
Technical details
Data in Higher Logic can be categorized as:
- User Information/Standard Demographics - The data that is the basis for each user's profile in Thrive Community.
- Groups - There are two types of groups in Thrive Community -- community groups and security groups -- and each has a distinct function.
- Custom Demographics - These are any additional fields and properties associated to users.
- Meetings - These are calendar events that work with the corresponding event calendar modules in Thrive Community.
Technical requirements
You must meet the following technical requirements in order to ensure a viable integration between Higher Logic and Salesforce.
- You must have a version of Salesforce that has the API provisioned. According to Salesforce, the Enterprise and Unlimited editions have the API enabled by default. The Professional edition requires an additional fee for API access.
- You must provide an account that has API access for Higher Logic to use. The contact username can be anything, but the primary email address must be integration@higherlogic.com. If a user is logging in from an unexpected IP, Salesforce will prompt the user for a verification code sent to this email address. With the email address set, any Higher Logic staff member can log in to the environment and debug any issues that arise.
- The user account that Higher Logic uses for API access must have read permissions on:
- Contact object - Read/View All
- Account object - Read/View All
- HL Activity custom object - Read/Write/Create/Edit/View All/Modify All
- Community Group object - Read/View All
- Community Group Member object - Read/View All
- Badge object - Read/View All
- Badge Type object - Read/View All
- Order - Read/View All
- Event - Read/View All
- Event Attendee - Read/View All
- Subscription - Read/View All
- Item - Read/View All
- Ideally, the user will be a system administrator so that the Higher Logic account is able to install custom fields and Flows.
The tables and queries below identify which fields within Fonteva/Salesforce and which object make up the many Higher Logic entities mentioned above.
User Information/Standard Demographics
This section includes information regarding the Higher Logic schema and any default fields and objects that constitute a user in Higher Logic. Subsections denote any significant deviation from the general user.
Users in Higher Logic are created from Contacts objects in Salesforce.
Table notes
- The fields in the Fonteva Default Field column are in the Contact object unless otherwise specified.
- This ID field is not configurable. Higher Logic uses the 18-digit case-safe ID which, by default, is hidden to Salesforce users. In order to see it, apply the CASESAFEID formula to the Contact.ID in a custom field or a report.
| Fonteva Default Field | Higher Logic Field & Use |
|---|---|
| ID | LegacyContactKey - The unique identifier of the user |
| OrderApi__Preferred_Email__c | Email Address - The email address of the user |
| FirstName | First Name - The first name of the user |
| LastName | Last Name - The last name of the user |
| Designation | Designation - A designation or credential (e.g., CPA) |
| Salutation | Prefix - A name prefix (Mr., Mrs., Dr.) |
| DonorApi__Suffix__c | Suffix - A name suffix (Jr., III) |
| Account.Name | Company Name - The name of the Salesforce Account with which the Contact is associated |
| Title Company | Title - A job title for the user |
| Nickname__c | Informal Name - A nickname for the user |
| AccountID | Parent Company ID - The ID of the Salesforce Account with which the Contact is associated |
| MemberId | Member ID - A secondary ID with which it is possible to identify contacts |
| MailingStreet | Address Line 1 |
| null | Address Line 2 |
| null | Address Line 3 |
| MailingCity | City |
| MailingState | State Province |
| MailingPostalCode | Postal Code - Zip code |
| MailingCountry | Country |
| MemberSince | Member Since - Date the user joined the organization (not a standard field in SF) |
| MemberExpiry | Member Expires - Date the user's membership expires (not a standard field in SF) |
| OrderApi__Preferred_Phone__c | Phone 1 |
| "PREFERRED" | Phone 1 Type |
| OrderApi__Work_Phone__c | Phone 2 |
| "WORK" | Phone 2 Type |
| MobilePhone | Phone 3 |
| "MOBILE" | Phone 3 Type |
| HomePhone | Phone 4 |
| "HOME" | Phone 4 Type |
| Active__c | IsActiveFlag - A boolean (checkbox) field which a contact must have checked in order to sync over |
| null | AMSDirectoryOptOut - A boolean (checkbox) field which will opt the contact out of showing in the directory |
| HasOptedOutOfEmail | ContactMeOptOut - A boolean (checkbox) field which will opt the user out of receiving emails from Higher Logic |
| MaidenName | Maiden Name |
| Birthdate | Birthday |
Company Users
This section includes information regarding the Higher Logic schema and any default fields and objects that constitute a user in Higher Logic. Subsections denote any significant deviation from the general user.
Company records in Higher Logic are pulled from the Account objects in Salesforce.
Table notes
- The fields in the Fonteva Default Field column are in the Account object unless otherwise specified.
- This ID field is not configurable. Higher Logic uses the 18-digit case-safe ID which, by default, is hidden to Salesforce users. In order to see it, apply the CASESAFEID formula to the Account.ID in a custom field or a report. Account IDs should have 001 as the first three digits. Higher Logic adds the "ACCT_" prefix for any Account when synced over.
| Fonteva Default Field | Higher Logic Field & Use |
|---|---|
| ID | LegacyContactKey - The unique identifier of the Account |
| Name | Company Name - The name of the Account |
| OrderApi__Account_Email__c | Email Address - The email of the Account |
| Phone | Phone 1 |
| Phone | Phone 1 Type |
| Fax | Phone 2 |
| Fax | Phone 2 Type |
| ShippingStreet | Address Line 1 |
| ShippingCity | City |
| ShippingState | State Province |
| ShippingPostalCode | Postal Code - Zip code |
| ShippingCountry | Country |
| MemberSince | Member Since - Date the user joined the organization (not a standard field in SF) |
| Website | Website - Company website |
| OrderApi__Primary_Contact__c | Primary Contact - ID of primary Contact |
Groups
This section includes any information regarding the Higher Logic schema and any default fields and objects that constitute a group in Thrive Community. These will be categorized as community groups and security groups.
Community Groups - Fonteva Badges
Badge-based community groups are created using the OrderApi__Badges__r relationship on the Contact object.
- The fields in the Salesforce Field column are from OrderApi__Badges__r.
| Salesforce Field | Higher Logic Field |
|---|---|
| Id (This is always 18 digits and should resemble a1h55000002K6Y3AAK.) | LegacyGroupKey |
| Name | GroupName |
| "Badge" (This is a hard-coded string.) | GroupType |
| Name | GroupDescription |
| null | GroupRole |
| OrderApi__Awarded_Date__c | SinceDate |
| OrderApi__Awarded_Date__c | StartDate |
| OrderApi__Expired_Date__c | EndDate |
Standard SOQL query
SELECT
OrderApi__Badge_Type__r.Name,
OrderApi__Badge_Type__r.ID,
OrderApi__Awarded_Date__c,
OrderApi__Expired_Date__c
FROM
OrderApi__Badges__r
WHERE
OrderApi__Is_Active__c = true
AND OrderApi__Badge_Type__r.OrderApi__Is_Active__c = true
AND IsDeleted = false"
Community Groups - Fonteva Memberships
Membership-based community groups are created using the OrderApi__Subscriptions__r relationship on the Contact object.
- The fields in the Salesforce Field column are from OrderApi__Subscriptions__r.
- GroupName and GroupDescription are each constructed using two inherent relationships within Memberships - name and the class name.
| Salesforce Field | Higher Logic Field |
|---|---|
| Id (This is always 18 digits and should resemble a1h000000000000000.) | LegacyGroupKey |
| {OrderApi__Item_Class__r.Name} - {OrderApi__Item__r.Name} | GroupName |
| "Subscription" (This is a hard-coded string.) | GroupType |
| {OrderApi__Item_Class__r.Name} - {OrderApi__Item__r.Name} | GroupDescription |
| null | GroupRole |
| OrderApi__Current_Term_Start_Date__c | SinceDate |
| OrderApi__Current_Term_Start_Date__c | StartDate |
| OrderApi__Current_Term_End_Date__c | EndDate |
Standard SOQL query
SELECT
OrderApi__Current_Term_Start_Date__c,
OrderApi__Current_Term_End_Date__c,
OrderApi__Item__r.Name,
OrderApi__Item_Class__r.Id
OrderApi__Item_Class__r.Name
OrderApi__Item__r.Id
FROM
OrderApi__Subscriptions__r
WHERE
IsDeleted = false
AND OrderApi__Is_Cancelled__c = false
AND OrderApi__Is_Suspended__c = false
Community Groups - Fonteva Community Group
Community Group-based community groups are created using the PagesApi__Community_Group_Members__r relationship. Community Group Members is the joiner object between Contact and Community Groups.
- The fields in the Salesforce Field column are from PagesApi__Community_Group_Members__r.
| Salesforce Field | Higher Logic Field |
|---|---|
| Id (This is always 18 digits and should resemble a1h000000000000000.) | LegacyGroupKey |
| Name | GroupName |
| "Community" (This is a hard-coded string.) | GroupType |
| Name | GroupDescription |
| PagesApi__Role__c | GroupRole |
| PagesApi__Activated_Date__c | SinceDate |
| PagesApi__Activated_Date__c | StartDate |
| PagesApi__Deactivated_Date__c | EndDate |
Standard SOQL query
SELECT
PagesApi__Community_Group__r.Name,
PagesApi__Community_Group__r.ID,
PagesApi__Role__c,
PagesApi__Activated_Date__c,
PagesApi__Deactivated_Date__c,
FROM
PagesApi__Community_Group_Members__r
WHERE
IsDeleted = false
AND PagesApi__Is_Active__c = true
Community Groups - Fonteva Events
Event-based community groups are created using the EventApi__Attendees__r relationship. This relationship acts as a joiner between Event and Contact. Most of the fields that populate an event-based community group come from the Event object dictated by the relationship EventApi__Event__r.
- The fields in the Salesforce Field column are from EventApi__Event__r.
| Salesforce Field | Higher Logic Field |
|---|---|
| Id (This is always 18 digits and should resemble a1h000000000000000.) | LegacyGroupKey |
| Name | GroupName |
| "Event" (This is a hard-coded string.) | GroupType |
| Name | GroupDescription |
| "Member" (This is a hard-coded string.) | GroupRole |
| null | SinceDate |
| null | StartDate |
| EventApi__End_Date_Time__c | EndDate |
Standard SOQL query
SELECT
EventApi__Event__r.Name,
EventApi__Event__r.Id,
EventApi__Event__r.EventApi__Start_Date_Time__c,
EventApi__Event__r.EventApi__End_Date_Time__c,
EventApi__Status__c
FROM
EventApi__Attendees__r
WHERE
IsDeleted = false
AND EventApi__Event__r.IsDeleted = false
Security Groups
Groups that act as security groups can be created from the aforementioned Fonteva Badges and Fonteva Memberships. The schemas and queries are identical.
Custom demographics
Custom demographics can be created from checkboxes, pick lists, multi-pick fields, and free form (text) fields on the Contact object. These fields dictate how the custom demographics are created. See the table below for more information.
| Salesforce Field Type | Higher Logic Demographics Field Creation Details |
|---|---|
| Checkbox | Higher Logic creates "collapsed checkbox" demographics which require the PM to specify a demographic type and then the checkbox fields that should be grouped under that type. For example, a demographic type, Education Level, could have Bachelor's, Master's, and Ph.D. as checkbox fields. Contacts who check the Bachelor's checkbox would have the Bachelor's demographic under the Education Level demographic type in Higher Logic. All checkbox demographics must be synced in this way, even single checkbox fields that may not be part of logical groupings. Specifying the demographic type and one checkbox field will create a demographic type and assign Contacts who check that box a demographic under that type based on that field. |
| Pick list | A demographic will be created for each pick list option that is selected by at least one contact syncing to HL. For example, if the pick list field is called Specialty and the options are Running, Jumping, and Swimming, we will create demographics using those labels. Demographics are created for only those options that are selected. |
| Multi-pick | A demographic will be created for each pick list option, but in this case, contacts can select multiple options and be assigned multiple demographics from this field. |
| Free form | A demographic will be created, using the field name, as a Higher Logic free form demographic with the values of the field determining the demographic values. |
Meetings
This section includes any information regarding the Higher Logic schema and any default fields and objects that constitute a meeting (or calendar event) in Higher Logic.
Fonteva Events
Meetings are created using the Fonteva Events object. Higher Logic uses the EventApi__Event__c object for the event information and the EventApi__Venues__r object relationship for address details associated with a meeting.
- The fields in the Fonteva Default Field column are from EventApi__Event__c.
| Fonteva Default Field | Higher Logic Event Field |
|---|---|
| EventApi__Description__c | Event Description |
| URLEventApi__Registration_URL__c | Reg Redirect |
| Event_URL__c | Detail URL |
| EventApi__Community_Group__c | Community Key |
| EventApi__Display_Name__c | Event Title |
| EventApi__Display_Name__c | Short Title |
| EventApi__Start_Date_Time__c | Start DateTime |
| EventApi__End_Date_Time__c | End DateTime |
| EventApi__Is_Active__c EventApi__Is_Published__c NOT IsDeleted |
IsActive This field is a combination of these three fields. They must return true (except for IsDeleted) for the event to come over. |
| EventApi__Venues__r.Name | Address 1 |
| EventApi__Venues__r.EventApi__Street__c | Address 2 |
| EventApi__Venues__r.EventApi__City__c | City |
|
EventApi__Venues__r.EventApi__State__c |
State Province Code |
|
EventApi__Venues__r.EventApi__Postal_Code__c |
Postal Code |
|
EventApi__Venues__r.EventApi__Country__c |
Country Code |
|
EventApi__Venues__r.EventApi__Phone__c |
Phone 1 |
| "Contact Phone" | Phone 1 Type |
The event refresh uses one SOQL query to retrieve any events that were created since the latest successful event refresh.
SELECT
EventApi__Description__c,
EventApi__Display_Name__c,
EventApi__End_Date_Time__c,
Event_URL__c, Id,
EventApi__Registration_URL__c,
EventApi__Is_Published__c,
EventApi__Is_Active__c,
IsDeleted,
EventApi__Start_Date_Time__c,
EventApi__Status__c,
EventApi__Time_Zone__c,
EventApi__Event_Category__r.Id,
EventApi__Event_Category__r.Name,
EventApi__Community_Group__c,
(SELECT
Name,
EventApi__Street__c,
EventApi__City__c,
EventApi__State__c,
EventApi__Postal_Code__c,
EventApi__Country__c,
EventApi__Phone__c
FROM
EventApi__Venues__r)
FROM
EventApi__Event__c
WHERE
CreatedDate >= {date} OR LastModifiedDate >= {date}
Common questions
Why does the Higher Logic user need system administrator privileges?
Technically, the Higher Logic user does not require these privileges; however, having them does make things easier. Along with allowing the implementation project manager to complete the entire integration unaided, it offers protection from the following scenarios:
- The client creates a custom profile for the Higher Logic user with only the specific necessary permissions.
- Sometime in the future, possibly years, the client makes a change to or deletes this profile because they do not realize it's used by and important for their Higher Logic integration.
- Their integration breaks.
This user is not in a Higher Logic category (demographic, community, security group); why?
Ensure that the Contact's data is correct in Salesforce and that they are not disabled in the Higher Logic system. Use the Display Data button on the Sync Backend Database page to see what Higher Logic is receiving from Salesforce.
The OrderApi__Badges__r/other necessary relationship is not a valid relationship on Contact.
Make sure that the account that Higher Logic is using for the integration has view permissions to all the Fonteva objects:
Contact object - Read/View All
Account object - Read/View All
HL Activity custom object - Read/Write/Create/Edit/View All/Modify All
Community Group object - Read/View All
Community Group Member object - Read/View All
Badge object - Read/View All
Order - Read/View All
Event - Read/View All
Event Attendee - Read/View All
Why am I getting a "Field__c does not exist." message?
This error happens when a field does not have the necessary permissions in being visible. This usually happens when a new Salesforce profile, instead of Administrator, is used for the integration. Make sure that the fields that “do not exist” are visible to the API account's profile.