Bboogle – Architecture and Technical Documentation
Patricia Goldweic, June 13th 2012
Architecture
The Bboogle project includes the following main components:

Building block-proper component, which supports the Blackboard-specific
Bboogle tools available in the plugin. It has access to the following independent
services.

A service called Google Integration Service (or 'Gint') which, although distributed
*within* the building block, actually constitutes an independent service that provides a
façade on top of certain Google services (provisioning, creation, retrieval and sharing of
content, etc.) that are relevant to LMS users.

A service called the Bboogle Teams service (or 'Teams') which, although also distributed
*within* the building block, actually constitutes another independent service whose
purpose is to facilitate small group collaboration by implementing functionality at a level
higher than the Gint service (the concepts of 'community', 'breakout' and 'Bboogle
team' are native to this independent service), while in turn using the Gint service as
needed to fulfill its goals.
An important design tenet within Bboogle has been the insistence on the independence of the
services used by the building block. The hope is that these services could one day be used by
other third party applications, likely outside of the Blackboard environment, and/or perhaps be
augmented so as to serve as cloud services useful to the educational community in general.
Although it is possible to deploy the ‘Bboogle platform’ in different configurations, depending
on where the services are actually located (either remotely to the building block, or collocated
with it), the desire to streamline implementation has driven Northwestern and Blackboard to
collaborate in an effort to offer to Blackboard users a configuration that is all-inclusive and does
not require installation of services externally to the Blackboard server.
This all-inclusive configuration is shown in the next diagram under the ‘Bboogle’ rectangle. The
larger square corresponds to the integration of the Bboogle and Bboogle Teams functionalities.
The blue squares correspond to services/components that could be deployed outside of the
LMS.
The Google Integration Service (‘Gint’)
This service acts as a stateful façade on top of Google Apps services which are relevant to LMSs:
provisioning of accounts and groups, retrieval, creation and sharing of Google documents,
calendars and sites. It is in charge of the low level interaction with Google so that third party
apps only need to concern themselves with their own business logic.
The service was natively designed as a web service that accepts a number of requests (some
http GET requests, but most are http POST requests) in specific, json-based formats. A utility
class (edu.northwestern.at.bboogle.common.utils.CommunicationsUtil) is provided -within
the common source- to access the Gint service remotely via http. Two main Gint Java servlets
are in charge of receiving these requests when the Gint service is used in a standalone way:
 GintRequestServlet is in charge of receiving and dispatching all provisioning-related
requests and requests that only modify the local Gint database.
 GintShareRequestServlet is in charge of receiving and dispatching all the content
creation and content sharing requests.
At a lower level than the servlets, and independently of whether Gint is used in standalone
mode or as a client within a third party app, Gint requests are actually executed by one of the
Gint request dispatchers: edu.northwestern.at.bboogle.gint.servlets.GintRequestDispatcher
and edu.northwestern.at.bboogle.gint.servlets.GintShareRequestDispatcher, depending on
whether the requests concern provisioning and database-related tasks, or content creation
and/or content sharing.
Gint Requests
Requests can be seen as the native functional and processing unit within the Gint service. The
edu.northwestern.at.bboogle.gint.data.GintRequest is the base class for all provisioning and
database-related Gint requests, while the
edu.northwestern.at.bboolge.gint.data.GintShareRequest is the base class for all content
creation and content sharing requests.
The two types of requests above have differing needs in terms of Google authentication, and
the corresponding base classes above provide the necessary support so that individual request
classes do not need to be concerned with the details of authentication.
Provisioning-based requests used the Google client login method of authentication, although
the adoption of 3-legged OAuth against a Google administrative account is in the roadmap (this
is the most desirable scenario, in which no administrative credentials need to be stored by the
application) . Content creation, retrieval and sharing requests use 2-legged OAuth to
authenticate against the different Google services.
Requests can be defined as either synchronous or asynchronous. An ‘offline’ field value of true
in the edu.northwestern.at.bboogle.gint.data.GintBaseRequest class -parent of both of the
above base request classes- indicates an asynchronous request that is to be executed in the
background request execution thread). Synchronous requests are queued up in a blocking
queue, which is managed by the
edu.northwestern.at.bboogle.gint.servlets.RequestProcessingService class.
All the requests dispatched within Gint get logged in the database in the GintTask table (see
later section).
Gint Scheduling
The latest expanded Gint service (new as of version 3.0.0) supports the scheduling of a few
types of requests: group membership, group membership deletions and group sharing, even
though this behavior is not exposed yet within Bboogle. See a later section on the Bboogle
Teams service to see how this functionality is being used there.
The scheduling of Gint requests is done through specific (meta) types of requests whose job
when executing is simply to create a Quartz job corresponding to one of the predefined job
types (see package edu.northwestern.at.bboogle.gint.quartz, which contains the job
definitions) , and which will in turn spawn a regular Gint request at the time the Quartz job is
scheduled for.
Quartz is currently used within the Gint service in non-persistent mode, so relevant Quartz jobs
need to be loaded into memory when the Bboogle block gets initialized. Note that the only jobs
that need to be (re) loaded are those whose schedule is in the future (the rest can be safely
ignored, as they must already have been taken care of).
Membership voting algorithm
When the possibility exists that requests for membership in certain groups may overlap, or may
arrive very close to each other (or simultaneously), there is a need to keep counters that
represent the number of votes that were cast for or against a certain user’s membership in a
certain group. Then a task is run periodically
(edu.northwestern.at.bboogle.gint.quartz.GroupMembershipPeriodicRunJob) that inspects
these counters in search for those records that indicate the need to actually run a group
membership or group membership deletion task.
While certain tools may require synchronous, immediate action (e.g. a dynamic link in Bboogle
may require that the user who is clicking on a link be made a member of the corresponding
team right then, if this is his/her first click, and he happened to join the Bb course *after* the
Bboogle link was made by the instructor), other tools do not require such immediacy, and can
simply execute ‘voting’ requests instead of direct group membership requests. In these cases,
the counter corresponding to the relevant user/group pair is incremented or decremented as
needed.
There are a few configuration parameters which are directly related to the workings of this
algorithm, as follows:
 membershipVotingEnabled is a Boolean parameter indicating whether the algorithm
described above is in use (true by default)
 periodicTasksIntervalMinutes: an integer parameter representing the number of
minutes between successive runs of the periodic job which implements the membership
voting algorithm. The default value for this parameter is 10.
 designatedHostForPeriodicTasks: a string property holding the server hostname (prefix
only) for the server designated to run the periodic job, when running in a clustered
Tomcat configuration.
In addition to the above, configurable parameters, the algorithm manages internally an
additional parameter whose function is to keep track of the last time the periodic algorithm has
run to completion: lastPeriodicJobRuntime, which represents a time in milliseconds.
Persistence in the Gint service
The Gint service uses the Java persistence framework (JPA) for persistence.
The service keeps its state by persisting, among other things, the results of its successful
interactions with Google services. In this way, it can avoid the re-execution of tasks that may be
requested by third party applications (e.g. the dynamic links within the Bboogle building block
send requests to Gint repeatedly). The following items are stored in Gint’s database:






Google account and Google group provisioning records. These represent successful
executions of the following types of request:
o Account existence requests (class involved:
edu.northwestern.at.bboogle.gint.persistence.GintAccount)
o Group provisioning and existence requests (class involved:
edu.northwestern.at.bboogle.gint.persistence.GintGroup)
Group membership records. These represent successful executions of the following
types of request:
o Group membership requests (class involved:
edu.northwestern.at.bboogle.gint.persistence.GintGroupMembership)
Content ownership records. These represent a user’s ownership over a certain piece of
content, and are created when third party applications (such as the Bboogle building
block) request the creation of ‘links/bookmarks’. Request types associated with this type
of record are:
o Link creation requests (class involved:
edu.northwestern.at.bboogle.gint.persistence.GintLink)
Publication records for particular content items (in the form of ownership records) in
particular LMS/third party app’s group entities (NOTE: these records concern
publication within an LMS, or a third party app, and *not* sharing operations within
Google Apps). Request types associated with this type of record are:
o Link creation requests (class involved:
edu.northwestern.at.bboogle.gint.persistence.GintPublication)
Sharing records for particular publication records (NOTE: these represent actual Google
Apps sharing requests). Represent successful executions of the following types of
request:
o Group sharing requests (class involved:
edu.northwestern.at.bboogle.gint.persistence.GintShareRecords)
Mapping records that associate a third party user id to a Google Apps user id. Request
types associated with these records are:
o Id mapping retrieval requests
o Id mapping saving requests (class involved:
edu.northwestern.at.bboogle.gint.persistence.IdMappingRecord)



Gint request execution records. These represent execution records of individual Gint
requests. (class involved: edu.northwestern.at.bboogle.gint.persistence.GintTask)
Scheduled Gint request records. These represent Gint requests that have been
scheduled to execute at some point in the future. They also record execution
information. (class involved:
edu.northwestern.at.bboogle.gint.persistence.GintScheduledTask)
Group membership votes (counters). These records represent outstanding votes
against/for the membership of a particular user in a particular group. When the periodic
task runs as part of the group membership voting algorithm (see section above), it
queries the database to find those counters that should trigger either a group
membership or a group membership deletion request. A counter is considered to be in
such state when
o It has been modified since the last run of the periodic task
o It has a different ‘sign’ than the current group membership record for the given
user/pair. That is, the counter may have a positive sign, but no group
membership record exists for the corresponding user/pair. Or, the counter has a
negative sign, and there *exists* a group membership record for the user/pair.
In the first case scenario, a group membership request should be executed. In
the second scenario, a group membership deletion request should be executed
instead.
These records are represented by the class:
edu.northwestern.at.bboogle.gint.persistence.GintGroupMembershipVotes
Most of the persistence-related functionality is implemented by the
edu.northwestern.at.bboogle.gint.PersistenceManager class, a singleton persistence service
within the Gint service.
Using Gint as a client
Local vs. Remote Clients
Since version 2.1.0.0, any third party application (e.g. Blackboard, for the case of the Bboogle
building block) can use the Gint service as a client in either remote or local modes. In a remote
implementation, the third party client communicates to the remote Gint service via http (as the
original Bboogle did), while a local implementation counts on a Gint service that is collocated
with the client application.
Facades
Within the Gint component, a special façade is available (since version 2.1.0Alpha) for Javabased third-party applications that want to use the Gint service as a client:
edu.northwestern.at.bboogle.gint.client.GintServiceInterface.
Prior to this version of Bboogle, only the building block component included such type of façade
onto Google Integration services:
edu.northwestern.at.bboogle.bb.services.GoogleAppsIntegrationInterface, although note that
it is augmented with Blackboard business logic.
The Gint component now also includes a couple of implementations for the new
GintServiceInterface described above, corresponding to local and remote modes of access to
Gint (edu.northwestern.at.bboogle.gint.client.GintServiceRemote and
edu.northwestern.at.bboogle.gint.client.local.GintServiceLocal). In a similar fashion, the
building block component has included (since 2.0.0) a couple of implementations for the
GoogleAppsIntegrationInterface which also correspond to local and remote modes of access to
Gint (edu.northwestern.at.bboogle.bb.services.GoogleAppsIntegrationLocalService and
edu.northwestern.at.bboogle.bb.services.GoogleAppsIntegrationRemoteService ). Note that
the GoogleAppsIntegrationInterface (sometimes called GAPS for brevity) is essentially an
augmented GintServiceInterface which also has access to the Blackboard business logic. If the
goal becomes to streamline the code, one could greatly simplify the classes implementing
GoogleAppsIntegrationInterface so that they start delegating (most of the time) execution to a
corresponding GintServiceInterface implementation instance.
Configuration
When using Gint as a local client (from an application other than the Bboogle building block),
one needs to include a configuration-specific listener within the container web application:
edu.northwestern.at.bboogle.gint.client.local.GintContextListener. This class takes care of
performing the required service initialization. The distribution includes a set of simple sample
web applications that use Gint as a client (‘sample-gint-client-apps’ folder). Please check these
out before attempting to exercise this functionality.
GintServiceInterface sample methods:
public void ensureAccount(String accountID, String givenName, String familyName, String
email) throws IOException: ensures that a Google account exists for a given person, creating it if
necessary
public String ensureGroupMembership(String groupId, String memberId, String groupRole)
throws IOException: ensures that a given person is a member of the given group in the given
role (sends Google a membership request unless the membership is already stored in Gint’s
database)
public String scheduleGroupMembership(String groupId, String memberId, Date when,
String userid, String externalID): schedules the execution of a group membership request for
some time in the future
public void refreshProvisioningService(PropertiesFile config, String userid, String externalID):
refreshes the provisioning service instance with possibly new configuration details. (this
method is new in Gint 3.0.0.0)
GoogleAppsIntegrationInterface sample methods:
In addition to the above methods, consider:
public String obtainGoogleID(String userBatchUid): retrieve the Google id mapped to the given
Blackboard user batch uid
public RosterData retrieveRosterData(String userBatchUid, String courseBatchUid): retrieves
the Blackboard roster data for the given course and user.
Gint Java Packages:
edu.northwestern.at.bboogle.gint.servlets: contains the two servlets described earlier in this
document (GintRequestServlet and GintShareRequestServlet), the request dispatchers, and the
classes that support the queuing of requests
edu.northwestern.at.bboogle.gint.data: contains *all* the requests supported within the Gint
service. As long as no new authentication mode is required, adding a new request class will
effectively augment the functionality of the Gint service.
edu.northwestern.at.bboogle.gint.data.gservices: contains a series of wrappers on top of
Google services, which act as a higher level Google service façade accessible to the Gint request
classes.
edu.northwestern.at.bboogle.gint.persistence: defines all the Gint persistent classes and
Gint’s JPA-based persistence service.
edu.northwestern.at.bboogle.gint.quartz: defines a series of Quartz jobs in charge of spawning
particular types of Gint requests when they get executed. It also includes the periodic job that
implements the membership voting algorithm.
edu.northwestern.at.bboogle.gint.utilties: utilities used by Gint request classes
edu.northwestern.at.bboogle.gint.client: defines the Gint client libraries (that is, libraries that
support the use of Gint as a client, either remotely or locally. The sub package
edu.northwestern.at.bboogle.gint.client.local implements the logic required in case the thirdparty app and the Gint service are collocated in the same web application.
edu.northwestern.at.bboogle.gint.samples: defines sample code for applications that act as
Gint clients, both remotely and locally (the sub package
edu.northwestern.at.bboogle.gint.samples.local handles the case in which the third party app
uses the edu.northwestern.at.bboogle.gint.client.local package to access the Gint service).
The Bboogle Teams service (‘Teams’)
This service acts as another independent, stateful high level façade on top of Google Apps
services which are relevant to LMSs or third party apps in support of small group collaboration.
The Bboogle Teams service defines the concept of a community (a group or cohort of Google
Apps users), a breakout (a community’s partition of users into a set of disjoint groups/teams
that is only valid within a given time interval), and a Bboogle team (a group construct backed by
a Google Apps group, with associated Google Apps content – a Google site, a calendar, and a
documents collection- that is shared with the whole team). Third party applications using the
Bboogle Teams service as a client (e.g. the Bboogle building block), only need to interact with
the Bboogle Teams service via a high level API that is far removed from the details involved in
the corresponding Google interactions.
The Bboogle Teams service was natively designed as a set of JAX-RS-based restful web services
supporting the following operations:
 Creation, retrieval and update of communities
 Definition and update of time-restricted breakouts
 Definition and update of breakout memberships, representing the particular team
assignments within a given breakout. NOTE: this is a level removed from the Gint
membership records stored within the Gint service. The Team’s service breakout
memberships are higher level definitions that only end up spawning Gint membership
records when their associated breakouts become valid.
 Storage of mappings between third party group entity constructs and the corresponding
Bboogle Teams concepts (e.g. when used by the Bboogle building block, it stores
mappings of Blackboard group sets to Bboogle Teams breakouts, Blackboard groups to
Bboogle Teams, and Blackboard courses to Bboogle Teams communities)
 Synchronization of third party group set entities with Bboogle Teams breakouts
(whereby the group assignments of the third party application determine the team
assignments within the corresponding Bboogle breakout).
Restful services included in Bboogle Teams:



The Community service (handles creation, retrieval and update of community objects).
Implemented by the edu.northwestern.at.teams.restful.TeamsCommunityService
class.
The Breakout service (handles creation, retrieval and update of breakout objects).
Implemented by the edu.northwestern.at.teams.restful.TeamsBreakoutService class.
The Breakout Membership service (handles definition and update of breakout
membership objects). Implemented by the
edu.northwestern.at.teams.restful.TeamsBreakoutMembershipService class.


The Team service (handles creation and update of team objects). Implemented by the
edu.northwestern.at.teams.restful.TeamsTeamService class.
The Person service (handles creation and update of Person objects, which represent the
valid user objects within Bboogle Teams). Implemented by the
edu.northwestern.at.teams.restful.TeamsPersonService class.
Other, non-native Teams services were created during development for convenience:
 The CMS service (handles mappings between CMS or other third-party app group
entities and the Bboogle Team entities; can also cache CMS/third party app roster
information). Implemented by the
edu.northwestern.at.teams.restful.TeamsCMSService class.
 A Teams ‘Gint’ service was added initially for convenience; not meant to be used by
third party apps that have direct access to the Gint service, as it in fact is a small
‘backdoor’ through Teams into the Gint service underneath it. Implemented by the
edu.northwestern.at.teams.restful.TeamsGintService class.
The class edu.northwestern.at.teams.restful.TeamsRestfulService serves as a base class for all
the classes that implement the native services above.
Bboogle Teams requests and execution
Although the Bboogle Teams service was designed natively as a set of JAX-RS-based restful web
services, there is also a request-level library built on top of the restful service classes. This is
provided in the package: edu.northwestern.at.teams.library, which defines Teams ‘request’
classes that correspond to all the methods supported by the restful services (note the
functional similarity between the edu.northwestern.at.teams.library and
edu.northwesternt.at.bboogle.gint.data packages –this last one defining the request library for
the Gint service).
The edu.northwestern.at.teams.library.TeamsRequest class is the base class for all the request
classes within the Teams service, while the edu.northwestern.at.teams.library.TeamsResponse
class is used to represent the responses (results) returned from the execution of Teams’
request classes.
Teams’ requests can be synchronous and asynchronous (an ‘offline’ field value of true in the
TeamsRequest class indicates an asynchronous request). Synchronous requests are executed in
real time, while asynchronous requests are queued up in a blocking queue, which is in turn
managed by the edu.northwestern.at.teams.servlets.TeamsRequestProcessingService class
within the background thread class:
edu.northwestern.at.teams.servlets.TeamsRequestProcessorThread.
Because the Teams service was natively designed as a set of restful web services, the individual
request classes (built on top) are all pretty shallow: they simply delegate processing to the class
that implements the corresponding restful web service.
Persistence in the Bboogle Teams service
Similarly to the Gint service, the Bboogle Teams service uses the Java Persistence framework
(JPA) for persistence.
The Teams database stores the entities which are native to the Teams service:







Community objects (edu.northwestern.at.teams.persistence.Community)
Person objects (edu.northwestern.at.teams.persistence.Person)
Breakout objects (edu.northwestern.at.teams.persistence.Breakout)
Team objects (edu.northwestern.at.teams.persistence.Team)
Breakout Membership objects
(edu.northwestern.at.teams.persistence.BreakoutMembership)
Relationships among the above object types (e.g. a relationship exists between
Communities and the Person instances who owned them, between Communities and
Team instances associated with them, between Communities and Breakout instances
associated with them, etc. These relationships are defined by fields within the above
Java classes)
Mappings between third-party group entities and the above Bboogle Teams entities
(three mapping tables are being stored: entities that map to Bboogle Teams
communities, entities that map to Bboogle Teams breakouts, and entities that map to
Bboogle Teams teams). See the classes
edu.northwestern.at.teams.persistence.CommunityIdMapping,
edu.northwestern.at.teams.persistence.TeamIdMapping, and
edu.northwestern.at.teams.BreakoutIdMapping).
The entities above are persisted to the database as soon as they are created due to requests
posted to the Teams service. Note that this is a level removed from the Google Apps services
that eventually get involved (by the Gint service) during the execution of Teams service
requests. Example: when an instructor clicks for the first time the Bboogle Teams control panel
tool within a course, a community object is created for this course. This generates a
synchronous request to the Gint service to create a corresponding Google Apps group for this
course’s community. Consider another example involving the use of the Bboogle Teams
synchronization tool for the first time with a particular Bb group set: when an instructor
submits a form in this tool, a set of team objects are created by the Team service. This in turn
spawns several (asynchronous) Gint requests (by the Teams service itself) aimed at creating
the associated Google site, calendar, documents collection, share all this content with the
corresponding team, and ensure ownership of all this content by the instructor exercising the
tool.
Most of the persistence-related functionality is implemented by the
edu.northwestern.at.teams.PersistenceService class, a singleton persistence service used
within Bboogle Teams.
Using Bboogle Teams as a client:
Local vs. Remote Teams Clients
Since version 3.0.0.0, any third party application (e.g. Blackboard, for the case of the Bboogle
building block) can use the Bboogle Teams service as a client in either remote or local modes. In
a remote implementation, the third party client communicates to the remote Teams service via
http (the class edu.northwestern.at.bboogle.common.utils.restfulCommunicationsUtil, is an
option for establishing this communication), while a local implementation counts on a Teams
service instance that is collocated with the client application.
Facades
A special façade is available within the Bboogle Teams component for third-party Java-based
applications that want to use the Teams service as a client:
edu.northwestern.at.teams.client.TeamsServiceInterface.
Similarly to the case of the use of the Gint service as a client within Blackboard, it is convenient
to provide a high level façade to Blackboard-based apps that also has access to the Blackboard
business logic. The class edu.northwestern.at.teams.bb.services.TeamsIntegrationInterface
plays this role. The classes that implement this interface were natively designed to delegate
most of the method executions to the corresponding TeamsServiceInterface implementation.
Remote and local implementations of the TeamsServiceInterface exist within the Teams
component itself: edu.northwestern.at.teams.client.local.TeamsServiceLocal and
edu.northwestern.at.teams.client.TeamsServiceRemote. Likewise, remote and local
implementations of the TeamsIntegrationInterface exist within the building block component:
edu.northwestern.at.teams.bb.services.local.TeamsIntegrationLocalService and
edu.northwestern.at.teams.bb.services.TeamsIntegrationRemoteService. As with the case of
the Gint service, these two last classes are wrappers around the corresponding
TeamsServiceInterface implementations, and they also have access to Blackboard business
logic.
Configuration
When using Bboogle Teams as a local client, one needs to include a configuration-specific
listener within the container web application:
edu.northwestern.at.teams.client.local.TeamsContextListener. This class takes care of
performing the required service initialization. The distribution includes a set of simple sample
web applications that use Bboogle Teams as a client (‘sample-teams-client-apps’ folder). Please
check these out before attempting to exercise this functionality.
TeamsServiceInterface sample methods:
public JSONArray obtainUserTeams(String personId, String communityId): retrieves a set of
Team objects that the given person has access to within the given community
public String retrieveCommunityIdMapping(String groupEntityId): retrieves the community
object mapped to the given groupEntityId value.
public JSONArray ensureTeamsForGroupSet(JSONArray groupsInfo, String groupEntityId, String
googleSiteTemplateUrl): ensures that a set of Bboogle teams exist that correspond with the
given set of third-party app groups. It uses the given Google site template to create the Google
sites that will be associated with the new Bboogle teams.
public void addOrUpdateBreakoutMemberships(JSONArray teamMembershipsJson, String
breakoutId, boolean replaceFlag, boolean synchFlag, boolean cmsCreated): adds or updates a
set of breakout memberships – given in json format- associated to a given breakout. A number
of Boolean flags are used to determine how already existent breakout memberships for the
given breakout should be updated.
TeamsIntegrationInterface sample methods:
same as above, plus:
public JSONObject verifyCorrespondingTeams(List<Group> groups, String courseBatchUid):
verifies whether each one in a set of Blackboard groups has a corresponding team in Bboogle
Teams
public ensureTeamsBreakout(Id groupSetId, String groupSetTitle, String courseBatchUid,
Date start, Date until): ensures that a Bboogle Teams breakout exists for the given Blackboard
group set, and that it is valid in the given time range.
public synchronizeGroupSetWithTeamsBreakout(String groupSet, String groupSetTitle, String
courseBatchUid): synchronizes a set of Blackboard group memberships (belonging to the given
group set) with their corresponding Bboogle Teams team memberships
Bboogle Teams Service Java packages
edu.northwestern.at.teams.persistence: defines the Teams persistent classes and Teams’ JPAbased persistence service (edu.northwestern.at.teams.persistence.PersistenceService).
edu.northwestern.at.teams.restful: defines each of the restful web services that are native to
the Teams service.
edu.northwestern.at.teams.library: defines the Teams ‘request’ classes that wrap functionality
provided by the restful web services.
edu.northwestern.at.teams.servlets: defines the servlets used by the Teams service (that is,
only a BootstrapServlet when configured in standalone mode), and classes that support the
queuing of Teams requests.
edu.northwestern.at.teams.services: defines interfaces (and implementations) representing
services that the Teams service itself *uses*. A singleton object belonging to the class:
edu.northwestern.at.teams.services.TeamService gathers all these services (the Gint and CMS
services, represented by the GintServiceInterface and TeamsCMSInterface interfaces) in a
centralized location that becomes easily accessible across all of the Teams service code.
edu.northwestern.at.teams.client: defines the Teams client libraries (that is, libraries which
support the use of the Teams service as a client within third-party apps, both in local and
remote modes). The classes: edu.northwestern.at.teams.client.local.TeamsServiceLocal and t
edu.northwestern.at.teams.client.TeamsServiceRemote support local and remote access
respectively.
edu.northwestern.at.teams.samples: defines sample code for applications that act as Teams
service clients, both remotely and locally.
The Building Block Component
The building block component of Bboogle is responsible for supporting all the LMS tools
available within the plugin. This component (a Java web application) uses the independent
services described in previous sections (Gint and Bboogle Teams services) via high level Java
APIs ( façades ). As explained earlier, these facades, which also have access to Blackboard
business logic, are: edu.northwestern.at.bboogle.bb.services.GoogleAppsIntegrationInterface
and edu.northwestern.at.teams.bb.services.TeamsIntegrationInterface.
Building Block Servlets and Execution of Requests
Bboogle has included two main Java servlets until version 3.0.0:

The SSO Bridge Servlet (edu.northwestern.at.bboogle.servlets.SSOBridgeServlet) is in
charge of implementing the dynamic behavior of Bboogle links within the LMS. It’s easy
to underestimate the importance of this servlet, but consider that it needs to:
a. Ensure that the user clicking on the link has appropriate access to the Blackboard
course that it represents
b. If the user is an instructor in the course, then it ensures that a Google Apps
group has already been created for the course, and that it has been fully
provisioned
c. If the user is a student, then it ensures that the student is already a member of
the corresponding Google Apps group
d. Finally, it ensures that the content that it represents has been shared in the
proper way with the associated Google Apps group

The Linking Servlet (edu.northwestern.at.blackboard.bookmarking.LinkSaveServlet) is
a general purpose servlet that supports the bookmarking of content of arbitrary types,
both in pull and push modes. In the particular case of Bboogle, Blackboard content types
have been created for the different types of content that Bboogle supports (Google
documents, calendars and sites). The pull functionality is at play when a Blackboard user
selects one of the Bboogle-provided custom content tools from the Blackboard user
interface (Google Docs, Google Calendar, or Google Sites), and is able to pull a content
item of that type from their Google Apps space into their Blackboard course. In contrast,
the push functionality is at play when the Google Apps user (which also happens to be a
Bb course instructor) , uses the Bboogle bookmarklet to bookmark a particular piece of
Google content while being immersed in the Google Apps user interface. When pushing
a bookmark in this way, the user can choose exactly where in Blackboard the bookmark
should be added to (that is, particular content folder within any course he/she is
instructing).
In version 3.0.0.0, Bboogle adds two additional servlets to support the Bboogle Teams tools:

The Teams SSO Bridge Servlet
(edu.northwestern.at.teams.bb.servlets.TeamsSSOBridgeServlet) is very similar to the
SSO Bridge Servlet but instead of supporting general purpose dynamic links within
Bboogle, it supports Bboogle Teams’ dynamic links within the Bboogle Teams
Blackboard course tool. As such, this servlet is responsible for:
o Ensuring that an instructor that clicks on the Bboogle Teams tool has already
been made an owner of the Bboogle Teams community associated to the
Blackboard course, as well as of all of the teams associated with the course, and
their content.
o Ensuring that the Google content associated with each team in the course has
already been shared with the Google Apps groups associated with the individual
teams.
o Ensuring that a student that clicks on the tool gains access only to the team/s the
student has been made a member of.

The Teams Controller Servlet
(edu.northwestern.at.teams.bb.servlets.TeamsControllerServlet) is responsible for
implementing the behavior associated with the Bboogle Teams synchronization tools. As
such, this servlet communicates directly with the Gint and Teams services to see that all
steps in the synchronization process are executed. That is,
o Ensuring that a Bboogle Teams community exists for the course,
o Ensuring that there is a Bboogle Teams breakout that corresponds to a particular
Blackboard group set, and:
o Ensuring that the Bb group set group assignments determine the Bboogle Teams
team assignments in the given breakout.
The base class for requests that are handled by this servlet is the BbTeamsRequest class
(edu.northwestern.eat.teams.bb.servlets.BbTeamsRequest)
Building Block java packages
edu.northwestern.at.bboogle.bb.config: supports initialization of the building block, Gint and
Teams services components within Bboogle. Also provides the hooks for configuring the JPA
provider to work with the Blackboard database.
edu.northwestern.at.bboogle.bb.services: defines the services that the building block uses and
provides easy access to them within a singleton object belonging to the
edu.northwestern.at.bboogle.bb.services.BboogleService class.
edu.northwestern.at.bboogle.bb.servlets: defines all the Java servlets used within the building
block and their supporting classes. Also includes classes that support the creation of custom
identity providers, and a building block-specific configuration service.
edu.northwestern.at.bboogle.bb.utils: defines utility classes used within the Bboogle building
block.
edu.northwestern.at.bboogle.blackboard: this package defines utility and service classes that
are appropriate for use within building blocks in general (independent of Bboogle). The sub
package edu.northwestern.at.bboogle.blackboard.bookmarking.custom defines the Bbooglespecific classes that are used with the general purpose bookmarking tool defined in the
edu.northwestern.at.blackboard.bookmarking sub package. The sub package
edu.northwestern.at.bboogle.blackboard.utils defines a set of utilities for building blocks,
independent of Bboogle.
edu.northwestern.at.bboogle.custom.bb: defines any custom code that Bboogle implementing
institutions need (e.g. the edu.northwestern.at.bboogle.custom.bb.NUIdentityManager is the
custom identity manager used at Northwestern University).
Customizing Identity Providers within Bboogle
The building block component of Bboogle includes a Java interface
(edu.northwestern.at.bboogle.bb.servlets.data.IdentityCorresponder), base implementation
(edu.nortwhestern.at.bboogle.bb.servlets.data.IdentityManagerBase) and related
customization mechanism which supports the creation of custom identity providers.
More specifically, by creating custom implementations of this interface, institutions can provide
hooks to their institutional polices for assigning Google ids to Blackboard user ids, for naming
Google Apps groups, for assigning group roles to Bb users in these Google Apps groups, and
even for flexibly determining whether users Google accounts should be automatically
provisioned by Bboogle or not. The methods in this Java interface are:
public String getCorrespondingUserId (String userBatchUid);
This method determines the particular Google user id that corresponds to a given Blackboard
user batch uid. Note that this may well be the only method that needs to be customized in
many cases. By default, the identity mapping is used (although the return value needs to
include the fully qualified Google id)
public String getCorrespondingGroupId(String courseBatchUid);
This method determines the particular Google Apps group id that corresponds to a given
Blackboard course batch uid. By default, the identity is used here too.
public String getCorrespondingGroupRole(String BbCourseRole);
This method determines the particular group role within Google Apps groups that corresponds
to a given Blackboard course role. By default, instructors are mapped to the ‘owner’ role, and
everyone else is mapped to the ‘member’ role.
public String isUserProvisionable(String userBatchUid);
This method determines whether a particular user should be automatically provisioned by
Bboogle or not. The default implementation uses the value of the special configuration
parameters (instructorAutoProvision, studentAutoProvision and othersAutoProvision) to
decide whether users should be provisioned or not.
There are a few configuration parameters which are directly related to Bboogle’s identity
management, as follows:
 instructorAutoProvision is a Boolean parameter indicating whether Bboogle should
automatically provision Google accounts for Blackboard course instructors
 studentAutoProvision: a Boolean parameter indicating whether Bboogle should
automatically provision Google accounts for Blackboard course students.
 othersAutoProvision: a Boolean parameter indicating whether Bboogle should
automatically provision Google accounts for users other than Blackboard course
instructors and Blackboard course students.



groupAutoProvision: a Boolean parameter indicating whether Bboogle should
automatically provision Google groups for Blackboard courses when an instructor first
uses a Bboogle tool within a course. This parameter should keep its default value of true
unless one is interested in using Bboogle *only* for purposes of single sign-on
functionality within Blackboard and Google Apps (as other Bboogle capabilities would be
broken with a setting of false)
enableOpenIDDiscovery: a Boolean parameter indicating whether an openID request
should be initiated by Bboogle in case a Blackboard to Google user id mapping is not
already recorded in Bboogle’s Gint database. Note that the Google Apps domain must
be configured to use openID for this parameter to function properly.
identityCorresponderClass: the full name of a Java class that implements the
IdentityCorresponder interface as explained above (default value is
edu.nortwhestern.at.bboogle.bb.servlets.data.IdentityManagerBase)
In addition to the above, configurable parameters, Bboogle manages internally a couple of
additional parameters that are only relevant when automated provisioning of accounts is
enabled (note: these parameters should eventually make it into the configuration panel):
provisionEmailEnabled determines whether an automatic email is sent to Google Apps account
holders when their accounts are created through Bboogle, and passwordChangeText holds a
custom suffix for this email that explains the custom process required – within a particular
institution- to change one’s Google account password.
Facilitating the Google SSO process within Bboogle
Although Bboogle does not require institutions to install a Blackboard to Google SSO solution, it
provides a much better user experience when such solution is in place. There is currently help
(in two different modes) within Bboogle for institutions that need/want to use a SAML-based
Google SSO provider as an SSO solution, as follows.
Those institutions for which having the SSO provider included within the Bboogle building block
is desirable*, can use a SAML-based provider included in the building block component of
Bboogle: edu.northwestern.at.bboogle.bb.servlets.ProcessSAMLResponseServlet.
On the other hand, institutions which would rather host their SAML-based Google SSO provider
outside of the Blackboard environment can use the sample code included within the Gint
service component: edu.northwestern.at.bboogle.gint.servlets.ProcessSAMLResponseServlet
as a Google SSO provider for testing purposes until they come up with their final solution. Note
that a trust relationship must be established between the Bboogle building block and this SSO
provider in order for the SSO from Blackboard to Google to work properly. The sample SSO
provider included within Bboogle is mostly provided so that institutions can see how to
implement the provider’s side of the trust relationship (Bboogle itself implements the other
side by saving a gintaccount cookie containing the fully qualified value of the Google user id for
the current Blackboard user)
There are a few configuration parameters which are directly related to Bboogle’s single sign-on
facilities, as follows:
 secureSSO is a Boolean parameter indicating whether the http cookies that Bboogle
saves in a user’s browser – in order to implement Bboogle’s side in the trust relationship
between Bboogle and the Google Apps SSO provider- should be secure -that is, include
an encrypted token- or not (default value is false).
 sharedSSOPass a string parameter storing a password value shared between Bboogle
and the Google SSO provider, upon which the trust relationship among the two parties
depends.
 digestAlgorithm is a string parameter storing the name of a digest algorithm that
Bboogle should use to calculate the encrypted token used when secureSSO is set to
true.
 cookieDomain is a string parameter holding the domain of the http cookie that Bboogle
stores as it implements its side in the trust relationship. .
 cookiePath is a string parameter holding the path of the http cookie that Bboogle stores
as it implements its side in the trust relationship.
*Because, for example, some institutions may not have the resources (or the desire) to
maintain a separate Google SSO provider and all their Google Apps users also have Blackboard
accounts. In such case, it is acceptable for institutions to require users to be logged into
Blackboard before they can log into Google Apps (which is the authentication mode used within
the SSO provider implemented in
edu.northwesternm.at.boogle.bb.servlets.ProcessSAMLResponseServlet ). Note that this is
the only SSO provider included (as of June 2012) within the certified Bboogle building block.