Learning Environment Connector Developer Guide - Settings XML - EduGarage (Blackboard Developers Network)

To simplify user deployment of a Learning Environment Connector, it is recommended that the LMS provide a mechanism to export all relevant settings in a single XML file. This file can then be imported into Blackboard Learn during creation of the Integration.

Implementation of this feature is optional. The alternative is to document the values that users should enter for the following fields on the Add Integration page:

Learning Environment Type
Learning Environment ID
SSO Settings
Authentication Settings

Settings XML file format

Element	Description
IntegrationProperties	Root element of file
IntegrationProperties.integrationId	Globally unique identifier for remote LMS. This same identifier will be included in all notification sent from the LMS to Blackboard Learn.
IntegrationProperties.targetSystem	Learning Environment Connector's identifier. This should match one of the values returned by the Connector's IntegrationExtension.getConnectorTypes method
IntegrationProperties.ssoSettings	This is a free-form field that can be used by the LMS to provide any information needed by the Connector implementation.
IntegrationProperties.authenticationSettings	This is a free-form field that can be used by the LMS to provide any information needed by the Connector implementation.

Example file

<?xml version="1.0" encoding="utf-8"?>
<IntegrationProperties xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <integrationId>SampleLmsUniqueId</integrationId>
  <targetSystem>SAMPLE</targetSystem>
  <ssoSettings>ssoServerUrl=http://myserver.bbbb.net:8001/webct/ssoServlet; 
    sharedSecret=groucho; frontEndHost=myserver.bbbb.net; frontEndHttpPort=8001; 
    frontEndHttpsPort=8002; frontEndCookieDomain=.bbbb.net</ssoSettings>
  <authenticationSettings>JndiContainerFactoryClass=weblogic.jndi.WLInitialContextFactory;
    jndiProviderUrl=t3://myserver.bbbb.net:8001; am=CsPortalSSOv1AuthenticationModule; 
    instlcid=2044122001; jndiUsername=jndiuser; jndiPassword=webct</authenticationSettings>
</IntegrationProperties>

Testing settings parser

After implementing the settings XML export within the LMS, you will want to test the parsing of this file:

Log into Blackboard Learn as an administrator
Navigate to Admin Panel > Learning Environment Integrations > Add Integration
Fill in the form
1. Go down to the "Import Settings from File" part of the form, and click Browse to select your exported settings XML file
2. Click Import Settings

After clicking Import Settings, you should see the following:

Learning Environment Type has been automatically set to Sample Connector
Learning Environment ID matches the <integrationId> value from the XML
SSO Settings matches the <ssoSettings> value from the XML
Authentication Settings matches the <authenticationSettings> value from the XML

Accessing integration settings from within a Connector

The integration settings can be accessed from within any of the Provider classes.

public class SampleAuthenticationProvider extends AbstractAuthenticationProvider implements AuthenticationProvider
{
  @Override
  public boolean login( Id userId, String password )
    throws PasswordChangeRequiredException, PasswordChangeForcedException
  {
    String ssoSettings = getIntegrationContext().getLmsIntegration().getSsoSettings();
    String authSettings = getIntegrationContext().getLmsIntegration().getAuthSettings();

    ...

    return false;
  }

To simplify access to our settings, we'll add a helper method that converts the settings blocks into Maps:

package blackboard.platform.integration.extension.sample;

import blackboard.platform.integration.service.IntegrationContext;

import java.util.*;

public class SampleSettingsHelper
{
  public static String getSsoSetting( IntegrationContext integrationContext, String settingKey )
  {
    Map<String, String> settings = parseSettingsText( integrationContext.getLmsIntegration().getSsoSettings() );
    return settings.get( settingKey );
  }

  public static String getAuthSetting( IntegrationContext integrationContext, String settingKey )
  {
    Map<String, String> settings = parseSettingsText( integrationContext.getLmsIntegration().getAuthSettings() );
    return settings.get( settingKey );
  }

  static Map<String, String> parseSettingsText( String settingsText )
  {
    Map<String, String> properties = new HashMap<String, String>();

    String[] parameters = settingsText.split( "\\s*;\\s*" );
    if ( null != parameters )
    {
      for ( String parameter : parameters )
      {
        if ( null == parameter )
          continue;

        parameter = parameter.trim();
        if ( parameter.length() == 0 )
          continue;

        String[] parts = parameter.split( "\\s*=\\s*", 2 );
        if ( null == parts || parts.length != 2 )
          continue;

        properties.put( parts[ 0 ], parts[ 1 ] );
      }
    }

    return properties;
  }
}