The Netforum Enterprise XML integration with Higher Logic Thrive Community (Thrive Community) is built on a system of stored procedures and views that are installed on your Netforum SQL database. Higher Logic calls Netforum's web service to directly execute the stored procedures and views. The data that is returned creates all the relevant Higher Logic objects, such as communities, demographics, security groups, calendar events, and user profiles.

Stored procedures and Views

The stored procedure's main goal is to be executed from the web service.

The view is responsible for capturing the information and creating the schema.

NOTE: Some stored procedures might simply be used for calling the view and reflecting the same schema.

This document explains the various stored procedures and the corresponding views, including the specific schema that must be followed for the data to come through correctly.

WARNING: Before you modify any stored procedures or views, consider that modifying them will have immediate results on the integration. Be careful and test before altering them.

Higher Logic services

Three Higher Logic services are included with the Netforum Enterprise XML integration:

• Periodic Refresh - an automatic job that runs every 30 minutes to identify users who have changed some field that Higher Logic is reading from Netforum.
  • Stored procedure: HigherLogic_GetChangedMembers
• Member Refresh - a full data pull from Netforum that updates the users' Higher Logic objects (communities, security groups, custom demographics, profile information).
  • Stored procedure: HigherLogic_GetMemberInfo
• Events Refresh - an automatic job that runs at the beginning of the Member Refresh. It handles the schema of events and the criteria for syncing events (a combination of the periodic and member refresh).t
  • Stored procedure: HigherLogic_GetChangedMeetings

Integration notes

AMS requirements - Along with being Netforum Enterprise, Higher Logic needs the X-Web Link and the E-Web Link. The Integration Analyst assigned to your case should be granted SQLAdmin access.

Establishing a connection to Netforum - The integration with Netforum is what Higher Logic defines as a SQL-based integration. The scope and location of data is explicitly contained within SQL views and stored procedures that are installed on the Netforum database. To establish a connection to the SQL views and stored procedures, Higher Logic uses Netforum's web service, XWeb. The web service offers the ExecuteMethod method to directly call a specific stored procedure by name in a Netforum database.

To connect to the Data Services API, Higher Logic requires:

Member Refresh

Member Refresh is responsible for pulling the user information and all the various mappings to each Higher Logic data object. These mappings can be the memberships to security groups, memberships to communities, additional custom demographics, etc. The logic is in the stored procedure HigherLogic_GetMemberInfo, which will execute all the other stored procedures for the different Higher Logic objects and should not be changed.

User base information

Base information for a user includes first name, last name, phone numbers, and other data. This information comes from the "HigherLogic_MemberDetails" view which is accessed via the "HigherLogic_GetMemberInfo" stored procedure. The logic provided can be modified, but the schema must remain the same.

HigherLogic_MemberDetails

NOTE: For Company records, if the NetforumNoCompanyData configuration = TRUE, only CompanyName data will be integrated. If an issue arises where the Company information is not syncing, this is the likely cause. Also, Company information cannot be managed in Higher Logic because users are not able to login as company records in our Communities.

Community memberships

Communities are created through user memberships. Each row that is returned from this view, "HigherLogic_MemberCommunityGroups", maps a user to a community in the Thrive Community site. Results from this view can range from a single community to various communities based on a specific community type. The view that is provided by default contains two blocks of SQL logic that will create two types of communities: committees and events. These have been tested and used with various clients but can be modified. To add customized community group logic, the schema below must be followed to create the memberships and appended to the view.

HigherLogic_memberCommunityGroups

For example, assume a test user with a Netforum User with a MemberKey of 00000001 and the date is 01/01/2019.

SELECT *
FROM HigherLogic_memberCommunityGroups
WHERE MemberKey = '00000001'

Running the SQL query above will display all communities that member 0000001 belongs to. Here's an example output with some edge cases to check for. For any columns that are left out, those are assumed to be NULL or are not relevant in this example.

User 0000001 is going to be in only one Thrive Community. When data is returned to Higher Logic, the data is filtered out so invalid date ranges are caught and removed. The memberships to "Test Community 2" and "Test Chapter" will not show up on the Higher Logic site because the BeginDate datetime is in the future or the EndDate is in the past. The first membership is valid so this user will show up under the roster of the AMS community called "Test Community 1" with a unique identifier of "TEST-COMM" for 9 days.

Security Group memberships

Security Group memberships are similar to the community memberships. Each row that is returned from this view, "HigherLogic_MemberSecurityGroups", maps a user to a security group in Higher Logic. Results from this view can range from a single security group to various security groups based on the implementation. These have been tested and used with various clients but can be modified. For adding customized security group logic, the schema below must be followed to create the memberships and appended to the view.

HigherLogic_MemberSecurityGroups

The integration filters for invalid date ranges when applying security group memberships. The SQL query is:

SELECT *  
FROM HigherLogic_MemberSecurityGroups
WHERE MemberKey = '00000001'

Custom demographics

The integration treats demographics similarly to communities and security groups. Each row that is returned from this view, "HigherLogic_CustomDemographics", maps a user to a custom demographic in Higher Logic. Results from this view can range from a single demographic to various demographics with different demographic categories based on the implementation. The view that is provided by default contains logic for building custom demographics from Netforum's demographics SQL table. These have been tested and used with various clients but can be modified. For adding customized demographic logic, the schema below must be followed to create the memberships and appended to the view.

HigherLogic_CustomDemographics

NOTE: All of the following fields are required.

SELECT *  
FROM HigherLogic_CustomDemographics 
WHERE MasterCustomerId = '00000001' 

The same example used in the community memberships section will be used here. Running the SQL query above will display all demographics that member 0000001 is a part of. Here's an example output with some edge cases and explanation. For any columns that are left out, those are assumed to be NULL or are not relevant in this example.

From this output table, Member 0000001 will have:

• "Monsters University" as the value returned for the "College Name" demographic type.
• the choice of "Red" for the "Favorite Color" demographic type.
• a multi-pick with two choices selected, "Bachelors" and "Masters" for the "Degrees Held" demographic type.

Periodic Refresh

Every 30 minutes, Higher Logic calls the stored procedure "HigherLogic_GetChangedMembers" to return a list of changed users. Every view has a ModDate field which will determine if a user requires an update on the Higher Logic side. Higher Logic sends over a date time of the last successful periodic refresh for the stored procedure to use which will query through all the views and compare all the ModDates for users that are being returned. If a user's ModDate matches the criteria, that user will be included in the list that comes back to Higher Logic.

Each view needs to have ModDate logic associated with each custom community, security group, or demographic. A general format would be like the example SQL below:

ISNULL(ChangeDate,AddDate)

Higher Logic needs to account for when a membership has been modified which is reflected in the ChangeDate. The AddDate is for when a user gets added to the community/security group, gets assigned a demographic, or is created.

Events Refresh

Events Refresh encompasses the Periodic Refresh and the Member Refresh in one service catered to calendar events.

Event data pull

The schema for what is pulled in a single event is in the events view, "USR_HL_MEETINGS_VW". This view is typically not modified.

Event sync

On a daily schedule, Higher Logic sends a timestamp to the Netforum API calling the stored procedure, "HigherLogic_GetChangedMeetings" to return a list of events that have been added or modified since the last successful events refresh call. The two fields mentioned in the previous schema, AddressModDate and ModDate, identify three important tables within Netforum where an event could have updated their information. The logic checks for a creation date and/or a modified date within Netforum to cover any case where an event can be created or updated.

Single Sign-on

Higher Logic uses Netforum's separate login-focused web service (eWeb) to create an integrated sign-on experience.

Installation requirements

SSO Web Service URL - The following URL is the link that users will use to enter in credentials and initiate the sign in process.

https://[domain]/eWeb/DynamicPage.aspx?WebCode=LoginRequired&Url_success

Extracting the Unique Identifier

1. User clicks the Sign in button on their Thrive Community site.

2. Higher Logic redirects to EWeb Login.

3. On successful login, Netforum returns an encrypted customer token for user log in.

4. Higher Logic uses xWeb to verify the token using Authenticate method.

5. Authenticate method returns related resources needed for authentication.

6. User clicks the Sign in button on their Thrive Community site.

Higher Logic uses both the eWeb and xWeb to trade the SSOToken into confirmation of a valid memberId so a member can gain access to Higher Logic.

MemberCentric/API authentication

For using the mobile application and the Thrive Community API, the Netforum integration supports an alternate way of authentication, using the services already provided by the Netforum xWeb service.

Using the WebLogin method, a token is retrieved and then Higher Logic validates using the same flow as eWeb SSO to authenticate the current user.

Activity Sync

Activity sync is a writeback feature that Higher Logic offers. This feature allows you to document activities that happen in Higher Logic to your Netforum database. This works the same way as the other services that use the xWeb web service. For each activity, Higher Logic sends activity information using the xWeb method InsertCustomerAction. During installation, Higher Logic will insert into the Netforum database a number of Guids that relate to the corresponding activities so that when the InsertCustomerAction method gets called, Activity type mapping is already present.

FAQs and common issues and solutions

General

What if we are currently using Netforum Enterprise without the XML solution, what happens to the integration?

We are upgrading Netforum instances. How does that affect our Higher Logic integration?

We are unsure/do not know if the installed stored procedures are the optimized versions. How can we make sure that we are using the correct versions?

Member Refresh

This user is not in this demographic, community, security group, etc.

Navigate to the sections under Member Refresh. Depending on which data object that the user is not a part of, running the view and looking at the logic will provide more insight. Make sure that any begin dates or end dates are in a valid date range.

Periodic Refresh

A user was added to a demographic, community, security group, etc. The Periodic Refresh did not pick up this user and their information is outdated. 

The logic for determining if a user has updated any integrated fields with Higher Logic is contained in each SQL view. Make sure that logic is correctly picking up the right dates and is coinciding with the Periodic Refresh service.

The SQL is returning the right information, but the service is still not picking up the users.

One reason can be a time zone difference. Create a case with Higher Logic Support to confirm that the time zones are being accounted for.

System.Web.Services.Protocols.SoapException: Invalid Security Credentials at Avectra.netForum.xWeb.xWebSecure.netForumXMLSecure.ExecuteMethod

The NetforumEnterpriseXMLIntegrationSetupSQLScript.sql install script has not been run on the database being queried.

Events Refresh

An event is not coming over from Netforum into Higher Logic.

• Make sure that events are enabled to come over via the integration. This option can be turned off, so create a case with Higher Logic Support to check whether it's enabled.

• Make sure that the event has a valid end date. Navigate to the Events Refresh section to see which view contains that information.

• The integration can be configured to only allow certain events into the platform with a certain event type. Create a case with Higher Logic Support to confirm which event types are being allowlisted.

Single Sign-on

A user that should have access is seeing a disabled account/insufficient privileges page.

Make sure that this user is returning with the correct information in the stored procedures for the Member Refresh. If the Higher Logic site has been set to limit access based on specific member types, check the Security Groups view and make sure this user has access to the allowlisted security groups.

A user tries to sign in to Higher Logic. The page redirects to the Netforum sign in page. When it redirects back, I am still not logged in.

This can be due to many factors:

• Make sure that there is no service outage on Netforum side. If Higher Logic is calling the Netforum XWeb and the service is down, SSO will be disrupted.
• Make sure that your current SSO configurations are correct and have not been changed. Any vendor information that is updated will make any web service calls from Higher Logic error out. This will also disrupt your integration.

Activity Sync

Activities are not being written even though we have everything set up.

Make sure that all fields listed in the Activity Sync section have been correctly set up. All fields must be set up correctly for activities to complete the writeback cycle.

We do not have the stored procedure or the activity codes and sub-codes in Netforum. How do we retrieve these SQL objects?

Create a case with Higher Logic Support after confirming that you have the Activity Sync module as part of your Higher Logic platform. The scripts will be sent over and then you will have to install them on your Netforum database.

Installation assets

NetforumEnterpriseXMLIntegrationSetupSQLScript.sql