E-mail | While not required, you should strongly consider securing communication with the Sakai server via SSL. See the administration guide for more details. |
There are two components in the connector source that control the various settings for proper operation. These are defined with default settings in the file bb-lec/bb-lec-pack/src/webapp/WEB-INF/components.xml under the names org.sakaiproject.lec.api.Config and org.sakaiproject.lec.api.WsConfig. These settings can (and in some cases should or must) be customized in the sakai.properties file for the particular integration.
Properties definitions
Global properties
cookieName - Required. The name of the session cookie used by Sakai and managed by Blackboard as part of the integration.
cookieDomain - Required. The domain in which the Sakai and Blackboard installations reside. These must have a shared domain name in order for Blackboard to successfully manage the session.
webservices.allowLogin - Required. This must be set to true to allow the Blackboard installation to communicate with the default provided web services connector implementation.
org.sakaiproject.lec.api.Config properties
 | The following override bean properties and need to use the 'property@org.sakaiproject.lec.api.Config' convention. See the example configuration below. |
These configuration values are used throughout the default implementation and should be applicable regardless of the underlying communication protocol.
integrationId - A unique integration identifier for the integration instance. The default value is 'sakai'. This needs to be customized if you are integrating multiple Sakai installations with a single Blackboard installation. This value needs to match the 'Learning Environment ID' value set in Blackboard for the learning environment integration instance.
siteTypeList - This is a comma-delimited list of site types that are to be integrated into Blackboard. By default this is the single site type of 'bb_lec', but should be customized to include all the types desired (e.g. 'project,portfolio').
userTypeList - This is a comma-delimited list of user types that are to be integrated into Blackboard. By default this is the single user type of 'bb_lec', but should be customized to include all the types desired.
observerEnabled - By default this is set to 'false', but most integrations will want to set this to 'true'. The event observer captures Sakai events related to the integration and periodically communicates them to Blackboard during runtime to keep data synchronized between installations. Enabling this may cause performance problems for large installations.
org.sakaiproject.lec.api.WsConfig properties
| The following override bean properties and need to use the 'property@org.sakaiproject.lec.api.WsConfig' convention. See the example configuration below. |
These configuration values are used by the provided default web services based implementation.
bbUri - Required. This is the base uri of the remote Blackboard installation with which Sakai is being integrated. For e.g. 'https://blackboard.syr.edu'.
syncUri - By default this is based on the value set for bbUri and typically will not need to be modified.
psk - Required. This is a shared secret required for communication between the Sakai and Blackboard installations. This needs to match the 'psk' value set in the 'Authentication Settings' field configured for the integration instance within Blackboard.
syncTimeout - Communication attempts during synchronization will timeout if not successful within this amount of time. By default this is set to '5000' milliseconds.
wssEnabled - Indicates whether web service security is enabled or not. By default this is set to 'true' and should not be disabled unless there are serious performance issues.
Example configuration
An example of some of these properties as found in a sakai.properties file:
... ## Bb/Sakai LEC Config # Config settings integrationId@org.sakaiproject.lec.api.Config=sakai siteTypeList@org.sakaiproject.lec.api.Config=portfolio,bb_lec observerEnabled@org.sakaiproject.lec.api.Config=true # WsConfig settings bbUri@org.sakaiproject.lec.api.WsConfig=https://sakai.syr.edu psk@org.sakaiproject.lec.api.WsConfig=examplepsksharedbetweensakaiandblackboard wssEnabled@org.sakaiproject.lec.api.WsConfig=true # Required session cookie settings cookieName=SAKAI_SESSION cookieDomain=.syr.edu # Enable web services webservices.allowlogin=true ...
Quartz job setup
One of the biggest advantages of the Blackboard Learning Environment Connector for Sakai is integration and management of data from Sakai into Blackboard. The provided implementation includes three 'Quartz' jobs that can be managed via the Sakai 'Job Scheduler' tool.
Sakai/Bb LEC Snapshot
Occasionally it is desirable to synchronize all Sakai user, site and enrollment data (associated with the appropriate user and site types) with the remote Blackboard installation. This is typically necessary when initially integrating an existing Sakai installation with Blackboard, or desirable once daily during off-peak times to completely synchronize desired data between the two systems. This job will write a snapshot file to sakai/snapshot/snapshot.xml containing all the Sakai data for synchronization. This file can then be processed by Blackboard like any other snapshot file. Details regarding the Blackboard snapshot process are beyond the scope of this documentation. Please reference the appropriate Blackboard manual.
Sakai/Bb LEC Runtime Sync
As mentioned, if event observation is enabled, the connector will track integration related events and queue them for processing during runtime. This job will send queued events to Blackboard so that data remains synchronized between the two systems. Ideally you'd want to schedule this job to run every minute or so (optimized based on desired delay and performance considerations) so that Blackboard is updated with changes made in Sakai.
 | It is unnecessary to schedule this job if event observation is disabled, and event observation should not be enabled without this job being scheduled (otherwise you'll have a queue of events that are never processed). |
| Since this feature relies on the "Integrated Learning System Gateway" Building Block in Blackboard, you must configure the "Secret Key" field in the settings for this Building Block to match the 'psk' value configured above. |
Sakai/Bb LEC User Eid Map Sync
Sakai references users internally using an ugly identifier that is not desirable for reference within Blackboard, so a more human-readable external identifier (username) is used instead. When a user is removed from Sakai, we can no longer retrieve the user record referenced by the internal identifier in order to retrieve the external user identifier so the user can be removed from the integration in Blackboard...unless we keep a map of the external identifier for reference in this case. If the external identifier is not found, the user will need to be manually removed from Blackboard (or removed by a snapshot process). This job simply updates a mapping of internal to external user identifiers based on existing user records. It is desirable to run this job once when adding an integration for a Sakai system with existing user data, and possibly once daily to make sure the map data is current.
This job is not absolutely necessary, but is helpful to eliminate the case of orphaned user records in Blackboard no longer associated with the integrated Sakai installation.
Typical setup
A typical setup would run the snapshot process once daily to generate a snapshot file which would be copied over to the Blackboard installation and processed so that a full synchronization is performed daily. A runtime synchronization job will run approximately every thirty seconds to send queued runtime events to Blackboard so data remains in sync between the daily snapshot processing. The user eid map sync job is run once after initial setup/installation and once daily to keep the map in sync.
Debug logging
If the connector isn't working as expected, try adding the following to your sakai.properties file to log debug output that may help during troubleshooting:
## Configure Logging log.config.count=4 log.config.1 = DEBUG.org.sakaiproject.lec log.config.2 = DEBUG.org.springframework.ws log.config.3 = DEBUG.httpclient.wire log.config.4 = DEBUG.org.apache.commons.httpclient
| Make sure to disable debug logging on your production system! |
See the installation guide for more information regarding log levels.