Knowledge Base

Legacy iMIS Integration API Bridge and SSO Installation Guide

  • Updated

Follow this documentation to setup the Higher Logic iMIS integration. Note that some terminology might not exactly line up so reach out if there are any questions/errors.

Higher Logic recommends having an integration account that can access the SQL database. This account can be in two forms: a Windows user or a SQL account. The main difference between these users is how authentication works with the SQL server, but either will work for the Higher Logic integration.

Do not delete this user (SQL or Windows) or the integration between iMIS and Higher Logic will go down.

Higher Logic assumes there are two servers for the iMIS application:

  1. The web server which usually hosts the iMIS application on a domain in Internet Information Services Manager (IIS). The iMIS installation files should also be on this server.
  2. The database server which usually hosts the SQL database that houses all the iMIS information. SQL Server Management Studio (SSMS) is usually installed on this server.

Some iMIS installations include all of the above functionality on one server. The database can be located on the web server or accessible on the web server. If that is the case, that is acceptable but the customer must make that clear.

Higher Logic will provide the following file structure in a compressed file:

  • Stored Procedures and Views

    • iMISStoredProcedures.sql

  • HigherLogic (HL API Bridge)

    • App_Code

      • DataServer.cs

      • HigherLogicProfile.cs

      • HigherLogicWebService.cs

      • LibraryUpdateWebService.cs

    • bin

    • HigherLogicWebService.asmx

    • web.config

  • SSO

    • HLLoginRedirect.aspx

    • HLLogoutRedirect.aspx

Installing stored procedures and views

  1. Navigate to your iMIS SQL server and open your SQL explorer. It should be SQL Server Management Studio (SSMS).

  2. Login using whichever account is designated for the Higher Logic integration.

    1. If this account is using SQL authentication, set that when logging into SSMS. If this account is using Windows authentication, set that when logging into SSMS.

  3. Copy the contents from iMISStoredProcedures.sql and paste them into the SSMS query window. Execute the query and it should create all the stored procedures and views.

  4. To check, navigate to them using the SSMS Object Explorer. You can see the views and stored procedures in the same location as all the other views and stored procedures.

Installing the Higher Logic API bridge

  1. Navigate to the iMIS Web Server.

  2. Copy the contents in the HigherLogic folder and put it in the C drive (Path should be C:\HigherLogic). This will serve as the folder with all the Higher Logic code. Do not move/remove this folder.

  3. Copy the iMIS DLL (.dll) files from the iMIS application’s bin folder. This is usually installed here (C:\Program Files\(x86)\ASI\iMIS\Net\bin). Copy everything in this folder and paste it in the Higher Logic bin folder (C:\HigherLogic\bin).

  4. Edits will need to be made to the web.config file provided in the HigherLogic folder. They will need to be changed to match the iMIS web.config (C:\Program Files\(x86)\ASI\iMIS\Net\web.config). Edit the Higher Logic web.config to reflect the corresponding values in the iMIS web.config.

    1. Authenticate.Anonymous.UserId (line 10)

    2. SecurityKey (line 19) – this should be a new, randomly generated GUID. Higher Logic will need this.

    3. System.WebLogin (line 20)

    4. System.WebPassword (line 21) - if this field does not exist in the iMIS web.config, remove this from the Higher Logic web.config.

    5. ImisWebServerUrl (line 23)

    6. Please add in the SOA section from the iMIS web.config to the Higher Logic web.config

      1. You will need to add in the SOA section in the configSections XML block. The iMIS web.config should have that section header so please copy that. It is usually after the SystemParams section header.

        <?xml version="1.0"?><configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <configSections>
    <sectionGroup name="iMIS">
      <section name="SystemParams" type="Asi.SystemConfig, Asi" />
      <section name="Soa" type="Asi.Soa.Core.Configuration.SoaConfiguration, Asi.Contracts" /> <----SHOULD LOOK LIKE THIS
    </sectionGroup>

      2. Place the SOA section after the SystemParams XML block but it must still be within the iMIS XML block.

        <?xml version="1.0"?><configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
  <configSections>
    <sectionGroup name="iMIS">
      <section name="SystemParams" type="Asi.SystemConfig, Asi" />
      <section name="Soa" type="Asi.Soa.Core.Configuration.SoaConfiguration, Asi.Contracts" /> <----SHOULD LOOK LIKE THIS
    </sectionGroup>
  </configSections>
  <iMIS>
    <SystemParams>
      <add key="Authenticate.Anonymous.Allow" value="true" />
      <add key="Authenticate.Anonymous.UserId" value="MANAGER" />
    </SystemParams>
      <Soa> <---- NEEDS TO FOLLOW THIS STRUCTURE
        ...
      </Soa>
  </iMIS>

    7. Please edit the connection strings (line 13) in the Higher Logic web.config to point to the iMIS SQL server.

      1. Server is the server name (ex. IMISPROD)

      2. Database will be the specific database name (ex. PROD_IMIS, iMIS, [Organization Code]).

      3. User credentials - please note if Higher Logic’s integration will be using a SQL user or a Windows user.

        1. If using a SQL user, please edit the connection strings to look like so

          <add name="AMSConnection" connectionString="Server=[Server Name];Database=[Database Name];User ID=[HL Integration Username];Password=[HL Integration Password];" />
<add name="DataSource.iMIS.Connection" connectionString="server=[Server Name];database=[Database Name];uid=[HL Integration Username];pwd=[HL Integration Password]" />

        2. If using a Windows user, please edit the connection strings to look like so

          <add name="AMSConnection" connectionString="Server=[Server Name];Database=[Database Name];Trusted_Connection=Yes;" />
<add name="DataSource.iMIS.Connection" connectionString="server=[Server Name];database=[Database Name];Trusted_Connection=Yes;" />

  5. The web.config should now be setup. Please navigate to IIS on the web server. You will need to create an application pool for the Higher Logic application. See the screenshot below:

     

    1. If Higher Logic is using a Windows user and the windows user has been set in the connection string on the web.config, right click the HigherLogic application pool and select “Advanced Settings”. You will see an option under “Process Model” called “Identity”.

       

    2. Hit the ellipsis button (…). Press the “Set” button and input the credentials of the Higher Logic integration user.

      Once set, the identity property on the previous menu should reflect the Higher Logic integration account.

  6. Go to view your “Sites” in IIS. The Higher Logic application needs to be publicly accessible, require no authentication to hit the page,and must have a domain binding. If those requirements are met, right click the site and select “Add Application”.

    Please make sure that the application pool is set to the one created earlier in this document. The physical path should be pointing to the HigherLogic folder containing the HigherLogicWebService.asmx

  7. The configuration of the bridge should be complete. Please test by hitting “Browse” on the HigherLogicWebService.asmx file within IIS’s Content Explorer. This should open it based on the site and the bindings associated with the selected site. It should open up a web browser pointing to the following domain: https://[site-binding]/HigherLogic/HigherLogicWebService.asmx. The site should look like this on success:

     

  8. Please test the Higher Logic refresh services to ensure that everything is running as expected.

    1. To test the periodic refresh, navigate to the web service URL (https://[site-binding]/HigherLogic/HigherLogicWebService.asmx) and click on “GetChangedMembers”. Enter in the security key for the securityKey parameter (this is the same value as what was configured in the web.config). Use today’s date in this format (YYYY-MM-DDT00:00:00) for the changedSince parameter. A list of member IDs should be returned in a new tab. Keep one member ID for the Member Refresh test.

    2. To test the member refresh, navigate to the web service URL (https://[site-binding]/HigherLogic/HigherLogicWebService.asmx) and click on “GetMemberDetails”. Enter in the security key for the securityKey parameter (this is the same value as what was configured in the web.config). Use the one member ID that was saved in the last test. That user’s information should be returned in a new tab.

Installing the SSO ASPX pages

In the SSO folder, there are two pages that do the following functionality:

  • HLLoginRedirect.aspx – This file handles initiating the sign-in process which includes redirecting the user to the iMIS sign in page and retrieving thiise mandatory user resources. Those user resources are sent back to a corresponding Higher Logic page which will process and validate the information.

  • HLLogoutRedirect.aspx – This file handles the sign-out process which includes clearing out the session of all login related cookies and redirecting back to the Higher Logic home page.

  1. Please place the two ASPX pages in the same directory as the iMIS Rise Sign_In.aspx page. The location of the Sign_In.aspx page varies with version and the installation can be customized. To determine the location, please navigate to your iMIS Sign_In.aspx page using a browser. Pay attention to the path contained in the URL as this will usually reveal the location of the page.

  2. The two ASPX pages have default values which need to be updated. On lines 8-11 in HLLoginRedirect.aspx, please change the following:

    1. Domain (line 8) – please change this to the main domain of your main site. For example, for a main site domain of “www.tenant.com”, the value would be “tenant.com”.

    2. communitySite (line 9) – please change this to your Higher Logic Thrive Community (Thrive Community) site URL.

    3. webserviceURL (line 10) – please change this to the URL of the Higher Logic API Bridge.

    4. webserviceToken (line 11) – please change this to the security key that lives in the web.config (which should be in the HigherLogic folder on the web server). Please see the steps for the installation of the Higher Logic API bridge to find this value.

    5. Navigate to line 98 of HLLoginRedirect.aspx. This URL needs to point to the iMIS Rise Sign_In.aspx URL. See below – please replace “https://example.tenant.org/EXAMPLEPATH/Sign_In.aspx”.

      Response.Redirect(String.Format("https://example.tenant.org/EXAMPLEPATH/Sign_In.aspx?ReturnUrl={0}%3FRedirect={1}",

  3. On HLLogoutRedirect.aspx, please change the domain variable to match what was put for HLLoginRedirect.aspx.

  4. Please ensure that the MasterPageFile and Inherits parameters at the top of both pages match the iMIS Rise Sign_In.aspx page.

    <%@ Page Language="c#" Title="Login" MasterPageFile="~/Templates/MasterPages/public.master"
    Inherits="Asi.ContentManagerNet.DisplayPageBase" %>

Finishing up

You’re done with the configuration! Please send these values back to your Higher Logic point of contact.

  1. SecurityKey - This was the SQL GUID generated for the web.config.

  2. The full URL of the Higher Logic API Bridge/Application. Should follow this format: https://[site-binding]/HigherLogic/HigherLogicWebService.asmx

  3. The URLs for the HLLoginRedirect.aspx and HLLogoutRedirect.aspx pages - these should be in the same place as the iMIS Rise Sign_In.aspx page that is being used by your iMIS application.

Common issues and troubleshooting

There are many different installations of iMIS that we have encountered. Here are some issues that we have run into when installing this integration.

I cannot find the iMIS application’s bin folder at C:\Program Files(x86)\ASI\iMIS\Net\bin.

It is possible that the bin folder is located elsewhere. Typically, the bin is in ASI\iMIS\Net\bin, so finding the ASI folder is the critical piece. Unfortunately, this could be in many locations on any given server. Please consult your technical team or the team that set up the iMIS installation if you’re unable to find the ASI folder.

There is a server runtime error when I hit the Higher Logic API Bridge URL.

You are currently seeing a general error that won’t provide much insight. Please call the page from within the iMIS web server. This will give a better error message.

“Navigation.config could not be found”.

Please find the Navigation.config file that lives in the NET folder within the iMIS installation. The default path is C:\Program Files\(x86)\ASI\iMIS\Net. Copy and paste that file into the HigherLogic folder (same place as the web.config)

“The entry DataSource.iMIS.Connection has already been added…”.

Please navigate to the Higher Logic web.config file and place a “<clear/>” statement before the Data.Connection parameter. It should look like this:

<connectionStrings>
  <clear/>
  <add name="AMSConnection" connectionString="Server=DBSERVER\SQLEXPRESS;Database=iMIS;User ID=sa;Password=pwd123;" />
  <add name="DataSource.iMIS.Connection" connectionString="server=DBSERVER\SQLEXPRESS;database=IMIS;uid=sa;pwd=pwd123" />
</connectionStrings>

When I try to refresh a user, I see a DataServer error.

This means that there was some issue with connecting to the database. Please check the specific error.

  • This can be due to an invalid set of user credentials for accessing the database. Please make sure that the Windows user or the SQL user that Higher Logic is using is still valid within the web.config file (under the connectionStrings section).

  • This can be due to a mismatch in schemas. Please make sure that the hlGetMemberDetails stored procedure and the table in the Member Refresh section of this document match. The most common case is for the DoNotEmail field. Here is what it should look like:

CAST(0 as bit) AS DoNotEmail

Any problems with Microsoft.Owin.

Please navigate to the bin folder in the Higher Logic application and remove all .dll files that relate to Microsoft.Owin.

public.master does not exist

Please make sure that the HLLoginRedirect.aspx and HLLogoutRedirect.aspx master page file headers match with what is put in the iMIS Rise Sign_In.aspx page.

An error that doesn’t match any of the above

Chances are that this installation is using a very old version of a web.config. Please never copy the web.config when moving to a new iMIS server/version. Always use the web.config provided by Higher Logic since many modifications were added to fix any version related errors of iMIS (that wasn’t cloud).

Was this article helpful?
0 out of 0 found this helpful
Return to top

Can’t find what you’re looking for?

Create a Case Call US Support