IMIS has a RESTful API available for its Cloud clients and those who are on iMIS 20.2 Service Pack F and greater. Higher Logic uses this API to create:

• contacts,
• events,
• group memberships, and
• demographics.

NOTE: The API endpoints that Higher Logic interacts with are available in the iMIS SDK for Postman, available here on GitHub.

AMS requirements

iMIS has two main product offerings:

• Enterprise (20)
• Professional (100)

The Higher Logic iMISRestMembershipProvider is compatible only with Enterprise, version 20.2, Service Pack F and greater.

Establishing connections

Higher Logic must be provided with the endpoint that Higher Logic will use to access the REST API, as well as credentials that have the Full User and Remote Services roles; both are necessary to access and interact with the API for the integration.

• This user must be specific to the Higher Logic integration.

Member Refresh

iMIS object definitions

Here is a definition of objects within the iMIS system that Higher Logic interacts with from the API. These will be referenced throughout this article.

• Party: The parent object for all contact types within iMIS.
  • Person: The object for individuals. Person objects are integrated as contacts into Higher Logic.
  • Organization: The object for companies or organizations.
  • ComboParty: The object used to represent individuals who are both an organization/company and an individual; used when an individual is a sole proprietorship or the sole representative of their organization. ComboParty objects are integrated as contacts when they have ComboParty.PersonName set to a value; otherwise they are treated as an Organization.

NOTE: All Party objects (Person, Organization, ComboParty) are retrieved from https://[ImisRestUrl]/api/PartyContact Base Information.

• GroupClass: The parent object for groups of type (e.g., Committee, Chapter, Section, Event, Dynamic Group, etc.).
• Group: The groups.
  • MemberDetails: An object returned for a subset of GroupClass objects, such as Chapter or Committee, that contains membership details that specify role.
• GroupMember: The object that establishes a relationship between Party objects and Group objects.

 

Field	AMS Field	Higher Logic Use
Legacy Contact Key	PersonData.PartyId	Unique identifier for the user within iMIS
Email Address	PersonData.Emails where Email.IsPrimary equals true	The email of the user
First Name	PersonData.PersonName.FirstName	The first name of the user
Last Name	personData.PersonName.LastName	The last name of the user
Prefix	PersonData.PersonName.NamePrefix	A name prefix (Mr., Mrs., Dr., etc.)
Suffix	PersonData.PersonName.NameSuffix	A name suffix (Jr., III, etc.)
Company Name	PersonData.PrimaryOrganization.Name	The name of the Account with which the Contact is associated in iMIS
Company Title	PersonData.PrimaryOrganization.Title	A job title for the user
Informal Name	PersonData.PersonName.InformalName	A nickname for the user
Parent Company ID	PersonData.PrimaryOrganization.OrganizationPartyId	The ID of the Account with which the Contact is associated in iMIS
Member ID	not assigned	A secondary ID with which it is possible to identify contacts
Address Line 1	Party..Address.AddressLines[0]	Address line 1
Address Line 2	Party..Address.AddressLines[1]	Address line 2
Address Line 3	Party..Address.AddressLines[2]	Address line 3
City	Party.Address.CityName	City
State Province	Party.,Address.CountrySubEntityCode	State/province
Postal Code	Party.Address.PostalCode	Zip code
Country	Party.Address.CountryCode	Country
Phone 1	Party.Phones where phoneType equals _Home Phone	Phone number 1
Phone 1 Type	_Home Phone	Phone number 1 type
Phone 2	Party.Phones where PhoneType equals _Work Phone	Phone number 2
Phone 2 Type	_Work Phone	Phone number 2 type
Phone 3	Party.Phones where PhoneType equals _Toll Free	Phone number 3
Phone 3 Type	_Toll Free	Phone number 3 type
Phone 4	Party.Phones where PhoneType equals _Fax	Phone number 4
Phone 4 Type	_Fax	Phone number 4 type
IsActiveFlag	Party.Status.ActiveStatus equals Active	A boolean (checkbox) field which a contact must have checked in order to sync over
Maiden Name	not assigned	Maiden name (not standard in iMIS)
Birthday	PersonData.BirthDay	Birthday (not standard in iMIS)

Company User Base information

The Organization object is used by Higher Logic to integrate company records. When a ComboParty object does not a have ComboParty.PersonName set to a value, it will be integrated as a company record.

Field	AMS Field	Higher Logic Use
LegacyContactKey	PersonData.PartyId	The unique identifier of the company
Company Name	PersonData.OrganizationName	The name of the company
Email Address	PersonData.Emails where Email.IsPrimary equals true	The email of the company
Phone 1	Party.Phones where phoneType equals _Home Phone	Phone number 1
Phone 1 type	_Home Phone	Phone number 1 type
Phone 2	Party.Phones where PhoneType equals _Work Phone	Phone number 2
Phone 2 type	_Work Phone	Phone number 2 type
Phone 3	Party.Phones where PhoneType equals _Toll Free	Phone number 3
Phone 3 type	_Toll Free	Phone number 3 type
Phone 4	Party.Phones where PhoneType equals _Fax	Phone number 4
Phone 4 type	_Fax	Phone number 4 type
IsActiveFlag	Party.Status.ActiveStatus equals Active	A boolean (checkbox) field which a contact must have checked in order to sync over
City	Party.Address.CityName	City
State Province	Party.,Address.CountrySubEntityCode	State/province
Postal Code	Party.Address.PostalCode	Zip code
Country	Party.Address.CountryCode	Country

Community Memberships

Community memberships are determined by the API endpoint GroupMember. Groups for community memberships can be created from any GroupClass within in iMIS, but the defaults are Event, Chapter, and Committee.

Other GroupClasses can be used as the basis of community formation but must be specified accessible from the API. Custom groups can be created via IQAs (documentation can be found here). If opting to create custom groups from IQAs, it is recommended to have the IQA run daily so that the information remains current.

Keep the following important points in mind regarding groups created dynamically from IQAs:

• Only groups that can be discovered by the API endpoint Group can be integrated. If the group cannot be queried from the API, it does not exist for all intents and purposes.
• Higher Logic will NOT write IQAs for clients. If writing the IQAs is not possible, contact ASI for assistance. Higher Logic cannot provide support for functionality within ASI’s products.

Group objects in iMIS can be divided into simple groups and those that have the MemberDetails object returned, such as iMIS Committees.

Simple groups are those without roles attached to them and where active status is determined by the field “IsActive” with optional date values of “JoinedOn” and “DropDate”.

Groups that have roles contain the MembershipDetails object. The MembershipDetails objects contains a collection of roles along with effective dates and expiration date per role for the GroupMember in question.

All GroupMember objects are retrieved from the following endpoint:

• https://[ImisRestUrl]/api/GroupMember?PartyId=[target Party.PartyId]

All GroupClass objects can be discovered from the following endpoint:

• https://[ImisRestUrl]/api/GroupClass

All Group objects can be discovered from the following endpoint

• https://[ImisRestUrl]/api/Group

Object schema

Higher Logic Community Field	AMS Field	Notes
LegacyGroupKey	Group.GroupId
GroupName	Group.Name
GroupType	GroupClass.GroupClassId
GroupRole	MembershipDetailsp[].Values.Role *	not available with simple groups
SinceDate	JoinDate,
StartDate	JoinDate, *MembershipDetails[].Values.EffectiveDate
EndDate	DropDate, *MembershipDetails[].Values.ExpirationDate

With simple groups, JoinDates and DropDates are optional values and can be inconsistent with IsActive status. For example, if today was 2020-02-01 and the DropDate for the group in question was 2019-12-31, the IsActive field can be set to true.

Dates are integrated by default and take precedence over active status. This is done because if a Party in iMIS has a change in membership to a group, no change is made to the UpdatedOn field on the corresponding Party record.

The integration can be configured to only look at IsActive status but this means all memberships are of indefinite duration. If a Party loses membership while JoinedDate and DropDate are set to be ignored community membership will only be reflected when that user/group is refreshed and prevents the automated processes within the site from remove expired memberships for contacts. It is highly recommended that workflows are implemented in iMIS to make dates accurate.

Security Group Memberships

Security groups are integrated the same way as community groups. Generally, the site is configured to create security groups based on the iMIS Member Types, but other groups can be used as security groups as long as they are discoverable from the API endpoint Group.

IQAs can also be used to place contacts into groups. In instances where memberships flow down from organizations to individuals, the client must specify what those contacts' member type is if they are using a Limit by Security Group list, because the Group.Name for Person objects may not be the same as it is for Organization objects.

Groups that are not simple groups will not have their roles integrated and the default role for every security group in Higher Logic will be set to “Member”.

Integrating Security Groups through IQAs instructions

1. Ensure IQA results are returning from iMIS' /Group endpoint. This does not happen by default. See these instructions from iMIS.
2. Each Group returned from that endpoint will have a "Group Class ID". The Higher Logic Thrive Community (Thrive Community) site needs to be configured to read IQA type groups as communities.

All IQA's have the same Group Class ID (3B630B49-2095-4B8E-A93D-61B30394D553) across all iMIS clients. This means that you can't target a single IQA to create a security group if more than one returns from the /Group endpoint.

Custom Demographics

Custom demographics can be integrated from IQAs that are created and deployed. Basic info on creating IQAs.

Demographics fall into two categories: freeform or standard. Anything that is not selected from a predefined field within iMIS is a freeform demographic; otherwise, everything else is a standard demographic.

All IQAs are retrieved from the following end point:

• https://[ImisRestUrl]/api//api/iqa?queryname=[IQA path provided by client]&parameter=[Target PartyId]

Configuring Demographics in OC

Here is an example response for IQA named $/HigherLogic_Demographic_iQAs/Ethnicity, (https://[ImisRestUrl]/api/iqa?queryname=$/HigherLogic_Demographic_iQAs/Ethnicity&parameter=23150):

Within the Properties object is a collection of Value objects. Each Value object has a Name attribute (the field name) and a Value attribute (the assigned value to this attribute). If there is no Value attribute in a value object, no value has been assigned for the Party. Each Value object is treated as a demographic type in OC, and in this response ‘Diversity’ and ‘DiversityOther’ would be separate demographic types and Diversity is a picklist, while 'DiversityOther' is a free form.

Demographic IQA instructions

Step 1: Create the folder to store Higher Logic demographic iQAs

1. While logged in as an admin, navigate to RiSE from the main menu.
2. Select Intelligent Query Architect to display the directory interface.
3. In the upper left-hand corner, click New and select Folder. This folder will store your iQAs used to populate demographic information in your Thrive Community.
4. Click the Allow only the following types of objects in this folder radio button, followed by Query. When finished it should look like this:

5. Click Save to continue.

Step 2: Generate the iQA

1. Once the folder has been created to store your iQAs, select the created folder.
2. Navigate to the upper left-hand corner and select New, followed by Query. The query interface will open.
3. At the upper-right, select Advanced mode from the dropdown.
4. For the required Name field, any value will suffice but it should indicate what business object is being targeted by the iQA. All other fields are optional. The result should look like the following:

Step 3: Select the Source and Implement a Filter

1. Click the menu option Source to select the Business object you want to generate demographics from.
2. Once the business object is selected, click Filters. The purpose of the filtering is to resolve the selected business object to an individual contact.
3. With the Filters table selected, in the Property column select the property that maps to the contact id on the business object.
4. In the Prompt column, select Optional (this will allow you to test the iQA once created).
5. Once completed, click the greyed out + icon. When finished it should look like the following:

Step 4: Select Display values

1. Click the Display tab to select the properties of the business object you want to turn into demographics in Higher Logic.
2. Click the dropdown labeled View selected columns.
3. Select View all columns to display all properties of the business object. The result should look like this:

Step 5: Test the generated iQA

1. From the Define tab, click the Run tab. The following form will appear:

2. Enter the Id of a user known to have values with this custom contact detail.
3. Click Find. The result should look like the one below:

In this example, the iQA FavoriteAnimal selects a property that is a picklist hence the list of values. If multiple properties were selected for a single business object, each property would be represented by another column in the result.

A common issue is not setting a WHERE clause in the IQA; this causes all values for all records to be returned by the query. IQAs must resolve to a single contact record and be queryable by the parent record's PartyID. Following the instructions above exactly will allow for testing to see if the IQA was correctly formulated or not within your iMIS instance.

Periodic Refresh

The following entities are queried during the periodic refresh:

• Party: By created on and updated on values since the last periodic refresh. This will grab all Person, Organization, and ComboParty objects that were created or updated since the last periodic refresh.

Events Refresh

Events are pulled once a day from Event endpoint as part of the periodic refresh using the Event object.

Event data pull

Event Field	AMS Field	Notes
Event Description	EventData.AdditionalDescription, EventData.Description	AdditionalDescription is the rich text description of the event that can include raw HTML, Description is a short description. This can be toggled via config param.
Community Key	EventData.EventId
Event Title	EventData.EventTypeName
Short Title	first 20 characters of EventData.EventTypeName
Start DateTime	EventData.StartDateTime
End DateTime	EventData.EndDateTime
IsActive	EventData.Status

Single Sign-On

Higher Logic leverages the functionality of the default SSO for cloud clients and Service Pack F for self-hosted clients. A client application is set up by following these instructions. The flow works by the user being directed to /HigherLogic/Security/ImisRestLoginBounce.aspx within OC when they click sign on and redirects the user to a sign-on portal content item created in RiSE. The ImisRestLoginBounce.aspx page is used because iMIS does not have a way of handling dynamic redirect targets, and the bounce page saves the page the user initiated the sign on as a session variable.

After the user is successfully authenticated by the portal, they are redirected to another content item that initiates a POST request to /HigherLogic/Security/ImisRestLoginBounce.aspx that contains a refresh_token that is used to resolve the user’s identity via the API and determine their authorization to the community. Upon successful authentication, the user is redirected back to where they initiated their sign-on request.

SSO setup instructions (included on the Technical Worksheet)

The setup process will require creating:

• a client application in RiSE,
• a redirect content item for authenticated users, and
• a content item that functions as the community sign-on portal.

Step 1: Create the client application

Follow the instructions in the iMIS Single Sign On (SSO) article.

Your Higher Logic implementation manager will provide a redirect URL in the following format (case-sensitive):

• https://[community_URL]/HigherLogic/Security/ImisRestLoginBounce.aspx

Provide the following to Higher Logic:

• Client ID - The Client ID can be any value but should indicate that it is in use by Higher Logic in some way (e.g., “HigherLogicApplicationID”).
• Client Secret - For the client secret a random 32-character string should be generated.
• SSO Portal URL - The URL for the content item in RiSE that functions as the community sign-on portal.

Step 2: Create the redirect to the Higher Logic Thrive Community

After creating the client application, create a content item to redirect authenticated users to Higher Logic following these instructions. It is advised that the client create a new directory to store this redirect content item, and place the community sign on portal there as well.

Step 3a: Create a Community Sign-On portal (20.3.x Cloud clients)

The process for creating the community sign-on portal is very similar to that used to create the redirect content item. Following the first two steps from above.

1. For the title, anything can be entered but the title should alert users that this is page is logging them into the community (“Community Portal” would be an appropriate choice). For Layout choose SingleColumn.

2. Click Add content.
3. In the Content gallery window, select Contact.
4. Search for Contact Sign In and click Ok.

5. In the next window the default settings will suffice. Enter "Community Sign In” for the name and click Ok. You will be navigated back to the Content designer window, and a preview of the portal will be available.

6. At the top of the window, select Redirect rules to display the following:

7. Change the Conditions for redirect option to User is authenticated.
8. Using the Target URL or shortcut for redirect field, select where to redirect users.
9. Click select and navigate to the directory that contains the redirect content item that was created to redirect users back to the Higher Logic Thrive Community. Once the redirect is selected, it should look like this:

10. Click save and publish.

Once the community portal page is published, Higher Logic will need the portal’s publish location so that users can be directed to this page when they want to sign into the community. This can be retrieved by double-clicking the Community Portal content item.

Step 3b: Create a Protected Content Item (20.2.x Service Pack F and greater)

Clients with the self-hosted versions of iMIS will not be able to create a custom Sign-On portal, because there are differences in how self-hosted iMIS handles authentication. Instead of creating a custom login portal, create a blank content item that points at the redirect SSO content item following the same logic as above, but set it to “Requires Authentication” to view. This will result in the user being directed to the default iMIS sign in portal, and after the user is authenticated the rest of the flow will be initiated as if they were a cloud client.

Single Log Out (SLO)

When a user clicks sign out in Higher Logic, their session will persist in iMIS because iMIS Cloud/REST does not offer a URI that will terminate a user's session that can be redirected to when a user terminates their session in Higher Logic. A solution is to redirect to a page created by the client within their iMIS instance post logout that reminds the user to terminate their session.

MemberCentric/API Authentication

If you have purchased the MemberCentric app or currently have it in place, contact your implementation manager to let them know. Higher Logic will need to set up OIDC bridge to allow for authentication from iMIS Rest for clients with 20.3.x Cloud clients.

Activity Sync

(applies only to clients with Activity Sync)

If your IMIS version is 20.2.x with Service Pack F or greater, Higher Logic will write back to the Activity object on their API.

For iMIS EMS (version 20.3.x and above), activities are written to the ContactInteraction object. Set up begins with Higher Logic running a tool to create the necessary ConctactInteraction objects in the your EMS instance. Once completed, you may select the Activity Subscriptions you want to start writing back in Admin.

Note

If you are not seeing the ContactInteraction object, you need to create a Business Object for it. To do so:

1. Open Rise > Business Object Designer.
2. Create a new Business Object and call it "Thrive_Interaction" (or any name you choose).
3. Click the Database tab.
4. Add tables and look for ContactInteraction.
5. Add this to the Business Object, and then save and publish the Business Object.
6. Add it to an iQA and the data will be available for use.

FAQ/common issues and solutions

Connection notes

It is highly recommended that the account Higher Logic uses to access the API is not shared by an active user; doing so may result in support tickets due to significant community disruption when someone changes their password and does not inform support.

Member Refresh

Standard Demographics: the default column width for the values returned by an IQA within the API is 100 characters. However, because of how iMIS denormalizes picklist values, it places all values in the same column for that selected property and the column width remains 100 characters.

• iMIS support can provide instructions on how to increase column width for IQAs.

Syncing profile images from iMIS

Can I sync profile pictures stored in IMIS Cloud?

• Profile images cannot be synced via the iMIS Rest. Profile photos in iMIS Rest/Cloud are protected resources and cannot be downloaded from the service.

Security Group Memberships

The Nonmember Security group membership is not coming over.

• End dates in the past are considered expired groups so make sure that the end date is either Null or '0001-01-01T00:00:00' for the membership to sync. If this does not fix the issue, please create a support case with Higher Logic to look into the issue deeper.

Can I integrate multiple Nonmember security groups?

• Clients may have more than one nonmember SG, but for them to sync to Higher Logic from iMIS in a Member Type SG, they will have to have Null or 0001-01-01T00:00:00 end date.

iQAs

Can iQAs be integrated as both Security Groups and Communities?

• Since all iQAs are associated with the same class id, integrating them as either security groups or communities will start the syncing of all of the iQAs into the corresponding object, so you cannot bring iQAs into both types without creating each of them as both communities and security groups. There is no way to separate them.

Single Sign-On

When a new integration is being setup a certificate must be purchased for the community domain. The Higher Logic Implementation project manager will work with our internal resources to provide information on setting up a CNAME record. This should be done prior to the integration; not doing so will mean that SSO will not work and delay implementation.

Users are not automatically being logged into the Thrive Community site when they navigate from an iMIS page to an OC page.

• Unlike legacy iMIS there is no passive check for if a user is authenticated or not. There is not a way to implement this currently by Higher Logic Users will need to click on Sign-In once they are brought over to Higher Logic from an external site.

Clicking Sign Out on the Thrive Community site does not terminate the session within iMIS.

• iMIS does not provide a content item that can be created or targeted to terminate active sessions in iMIS. Users can be directed to a custom page that warns them they need to click sign out at the top of the page.

Activity Sync

• With iMIS 20.2.x, the activity types must be set up in iMIS. There is not a way to automate this process from the API like there is with iMIS Cloud (20.3.x).