Blackboard Building Blocks™Blackboard Content System™

Presented By Daniel Cane

dcane@blackboard.com Monday, April __, 2005

Now a word from our lawyers…

Any statements in this presentation about future expectations, plans and prospects for Blackboard and other statements containing the words "believes," "anticipates," "plans," "expects," "will," and similar expressions, constitute forward-looking statements within the meaning of The Private Securities Litigation Reform Act of 1995. Actual results may differ materially from those indicated by such forward-looking statements as a result of various important factors, including the factors discussed in the "Risk Factors" section of our most recent 10-K filed with the SEC. In addition, the forward-looking statements included in this press release represent the Company's views as of April 11, 2005. The Company anticipates that subsequent events and developments will cause the Company's views to change. However, while the Company may elect to update these forward-looking statements at some point in the future, the Company specifically disclaims any obligation to do so. These forward-looking statements should not be relied upon as representing the Company's views as of any date subsequent to April 11, 2005. Blackboard, in its sole discretion, may delay or cancel the release of any product or functionality described in this presentation.

What shall we talk about?

• Blackboard Content System-specific Building Blocks (CS-B2)

• Blackboard Content System Building Blocks User Interface Hooks

• Blackboard Content System Building Blocks High Level Data Objects

• Using the Blackboard Content System Building Blocks API – How and where it differs from the Blackboard Learning System™

and Blackboard Community System™ APIs

• Brainstorming about cool things to do with this!

Now a word from our lawyers…

Any statements in this presentation about future expectations, plans and prospects for Blackboard and other statements containing the words "believes," "anticipates," "plans," "expects," "will," and similar expressions, constitute forward-looking statements within the meaning of The Private Securities Litigation Reform Act of 1995. Actual results may differ materially from those indicated by such forward-looking statements as a result of various important factors, including the factors discussed in the "Risk Factors" section of our most recent 10-K filed with the SEC. In addition, the forward-looking statements included in this press release represent the Company's views as of April 11, 2005. The Company anticipates that subsequent events and developments will cause the Company's views to change. However, while the Company may elect to update these forward-looking statements at some point in the future, the Company specifically disclaims any obligation to do so. These forward-looking statements should not be relied upon as representing the Company's views as of any date subsequent to April 11, 2005. Blackboard, in its sole discretion, may delay or cancel the release of any product or functionality described in this presentation.

Assumptions

• This presentation assumes a high-level understanding of Blackboard Learning System Building Blocks infrastructures such as– Top Level Package Structure

• Blackboard.data, Blackboard.persist, Blackboard.base, etc

– Blackboard Building Blocks™ -Blackboard Learning System Data Model

• Objects such as announcement, course, user

– Blackboard Building Blocks®-Blackboard Learning System Persistence Services

• Such as CourseDbLoader, CourseDbPersister, etc

– Familiarity with Blackboard Taglibrary– Understanding of the Blackboard Building Blocks packaging,

manifest, etc

Other Resources

• Blackboard Learning System Javadoc• Blackboard Content System Javadoc• Blackboard Building Blocks Developers Guide• Blackboard Building Blocks: Introduction to the Building

Blocks APIs and Runtime• Blackboard® Web Site• Blackboard Open-Source Listserv• Each other!

What Are Building Blocks?

• Blackboard Building Blocks are applications that developers build to extend the Blackboard platform and to integrate Blackboard software with external applications, content, or services.  They can include portal modules, content, specific tools, assessment engines, integration with library systems, campus bookstores, door access or print management systems just to name a few.  The possibilities are endless.

Blackboard Content System

• The Blackboard Content System uses the same Building Blocks infrastructure to enable developers to build new applications on top of the application, as well as take advantage of the underlying utility of the application itself.

• The APIs allow for a wide variety of access to everything from the creation and management of files and folders to their metadata, properties, and permissions. The APIs also enable programmatic access to many of the tools within the Blackboard Content System, such as the Learning Objects catalog, Portfolios, and Workflows.

When can I play?

• Starting with Application Pack 2, Blackboard Content System APIs are public!

• Enhanced APIs in Application Pack 3• Anticipated added Localization capabilities with

Blackboard Academic Suite™ Release 7.0

Where to start….

• I tend to first think of the “use-cases” for my application and then build user scenarios off them. Because of my background (I’m actually an Economist not a Computer Scientist) I tend to think of UI and workflow before I plan architecture, objects, and code.

• When the Blackboard Content System is installed, the APIs are available to use from the entire Blackboard Academic Suite, NOT just those installed which use Blackboard Content System specific UI hooks. – You can build things for students (tools, communication, portal

modules, portal tools, etc)– You can build things for instructors (control panel tools)– You can build things for the administrator (admin control panel)

Additional Blackboard Content System Integration Points (a.k.a. UI Hooks)• Blackboard Content System Tools. The link is added to the Tools box in

the folder view of the Content Collection menu, and the Tools menu available from the shortcut view of the Content Collection menu.

• Blackboard Content System Action Bar. The link is added to the drop-down menu at the end of the Action Bar on folder listing pages in the Content Collection. Action Bar Building Blocks act on the files and folders currently selected in the folder listing.

• Modify Content File. The link is added to the menu of options that appears when a user clicks Modify on a file in the Content Collection.

• Modify Content Folder. The link is added to the menu of options that appears when a user clicks Modify on a folder in the Content Collection.

• Manage Portfolio. The link is added to the menu of options that appears when a user clicks Manage on a Portfolio on the My Portfolios page.

• My Portfolios. The link is added to the My Portfolios box in the folder view of the Content Collection menu, and the Portfolios menu available from the shortcut view of the Content Collection menu.

Blackboard Content System Data Object Packages

• The data object definitions reside in the various sub-packages of blackboard.cms.

• The sub-packages are grouped into various functional areas like FileSystem or Portfolio.

Blackboard Content System Data Object sub-packagesbookmark Contains objects associated with Bookmarks in the

system. filesystem Contains objects used by the filesystem subsystem. This

is one of the primary sub-packages within the Blackboard Content System, and contains the objects which control files and directories as well as the “CSContent” object which is part of the Blackboard Content System permissions framework.

lrngobj Contains objects for interacting with the Learning Object Catalog.

metadata Contains classes for manipulating metadata templates.

portfolio Contains classes for interacting with the Portfolio system.

workflow Contains classes for interacting with the Workflow system.

Data Object Descriptions

Entity DescriptionCSEntry This is the base class for objects (file and folders)

in the filesystem. It contains the access control entries, location, size, and metadata for objects.

See package blackboard.cms.filesystemCSFile This class represents files on the filesystem. It

contains the method for setting and getting the actual data within a file, as well as, the type of file.

See package blackboard.cms.filesystem

Data Object Descriptions

CSDirectory This class represents a directory in the filesystem. Methods are available for managing quotas for each directory. These quotas are the total space allotted by the owner for all files and sub-directories contained in the directory.

See package blackboard.cms.filesystemCSCustomDirectory This class encapsulates “Special” directories in

the filesystem. More specifically, the directory contents of a CSCustomDirectory cannot be changed, as they are managed explicitly by Blackboard Content System. For instance, the /users, /courses directories are type CSCustomDirectory

See package blackboard.cms.filesystem

Data Object DescriptionsCSContext This key object controls the context used for

determining permissions to entries, as well as, controls management of transactions. A context is the top level state manager for a series of Blackboard Content System calls. For every set of actions grouped together into one transaction, a new context is created and used. A context instance contains transactional state for that request (for example, commit or rollback). All permission checking is done through calls on the context object. See package blackboard.cms.filesystem

CSAccessControlEntry The CSAccessControlEntry class provides a representation of an Access Control Entry within the Blackboard application. An object exposing the individual permissions of a file/directory for a specific user or list of users. Methods exist to both read and set the permissions.See package blackboard.cms.filesystem

Data Object DescriptionsLOItem The LOItem class provides a representation of a

Learning Object Item within the Blackboard application. Learning Object Items usually refer to a physical file or folder within the Blackboard Content System, with additional metadata and status information related as metadata.See package blackboard.cms.lrnobj

LOCategory The LOCategory class provides a representation of a Learning Object category within the Blackboard application.See package blackboard.cms.lrnobj

Portfolio The Portfolio class provides a representation of a Portfolio within the Blackboard application. See package blackboard.cms.portfolio

Workflow The Workflow class provides a representation of a Workflow within the Blackboard application. A Workflow must have a type associated with it.See package blackboard.cms.workflow

Using Blackboard Content System Data Objects • The following code demonstrates how to create a

Portfolio object. • Portfolio portTest = new Portfolio();• Creation of a data object in this way results in an object

with default values for all of the object’s attributes. To create a more useful Portfolio, it is necessary to create one that contains more than default values. To do this, create a default Portfolio object and call all of the appropriate “set” methods provided by the object.

Data object IDs

• Blackboard Content System objects use the same ID framework as Blackboard Learning System objects. – Objects have a getId() method on them– Object can be generally loaded and deleted byId()

Persistence and Managers

• The Blackboard Content System uses a simplified approach for loading, deleting, and saving objects. Each of the core data objects for Portfolio, Metadata, Learning Objects, Bookmarks, and Workflows has an associated Manager.

• For example, the Portfolio has a PortfolioManager class which has methods to deleteById(), loadById(), loadAccessibleByCourseId(), loadByOwner(), save(), and more. The methods within the managers are static, so they can be accessed directly.

Example of using IDs, Loaders, and Persisters• For example, to load a Portfolio, make a change to it, and

then save it:– Portfolio portLoaded = PortfolioManager.loadById(portId);

– portLoaded.setTitle(“Updated Title”);– PortfolioManager.save(portLoaded);

Using Blackboard Content System File System Objects • Blackboard Content System filesystem objects work in a

slightly different way then the other Blackboard API objects. For filesystem access, a Bb Content System Context must first be established. This context is used to group transactions, as well as handle permission checking.

Creating a Blackboard Content System Context• A context is the top level state manager for a series of Blackboard

Content System calls. • For every set of actions grouped together into one transaction, a

new context is created and used. • A context instance contains a transactional state for that request (for

example, commit or rollback). • All permission checking is done through calls on the Context object.• Without a Context, whenever an exception is thrown, the state of the

transactions involved would be unknown. – It would not be possible to know which transaction(s) needed to be

committed or rolled back.

– The context object is used to keep track of that state and allow or block commit attempts. Thus, the context object can be used to find out if the current transaction can be committed or not.

Creating a Blackboard Content System Context contd.• It is extremely important when using the context object to ensure that

you properly use a try{},catch{},finally{} block to commit() or rollback() each transaction. Not doing so properly may cause deadlocks, performance degradation and unexpected behavior.

• It is recommended to always use CSContext in the following way: CSContext ctxCS=null; try { ctxCS = CSContext.getContext(); //your code here } catch (Exception e) { ctxCS.rollback(); } finally { if (ctxCS!=null) { ctxCS.commit(); } }

More on Blackboard Content System Context• The CSContext.getContext() call also has the ability to

load context “as a specific user.” • This gives the programmer the ability to determine if that

user has sufficient privileges to operate on the designated CSEntry.

• For some operations, the standard user context may be inadequate to perform the desired operation. In that case, there is a CSContext.isSuperUser() method that can be used. – Setting this to “true” and then performing the operation is useful

under certain conditions.

Using the Blackboard Content System Context for Filesystem stuff..

• Once a CSContext is established. It is used to create new CSFiles and CSDirectories (sub classes of CSEntries).

• It is also used to load existing files and directories using the findEntry() method. The CSContext is further used to check if permissions for the current loaded context canRead(), canWrite(), canManage(), and canDelete() a specific CSEntry.

• The CSContext object is used to load, save, create, and manage the CSEntries in the file system.

Example of using Context and Entries• Goal: Write a program that will load a specific Blackboard

Content System Directory and print out the contents (filenames) of that directory.

• Assumptions– The user running the program has read access to the folder and

it’s contents.

Example of using Context and Entries// Loads the CSDirectory object /users/dcaneCSDirectory csDirMyUserDir = ctxCS.findEntry("/users/dcane");// Gets the contents of the directory as a ListList listDirectoryContents =

csDirMyUserDir.getDirectoryContents();// Iterate through the list and print out information on the

contentsIterator iterDirectoryContents =

listDirectoryContents.iterator();while (iterDirectoryContents.hasNext()){ // the List of a directory contains CSEntry items (which

can be other dirs or files) CSEntry csEntryItem = (CSEntry)

iterDirectoryContents.next(); out.println(“Hello there, I have found: “

+csEntryItem.getFullPath());}

“Special” Loaders for Course Dirs, User Dirs, etc• The CSContext also does some special loading for

course directories, user directories, and eReserve directories. These loaders will return CSDirectory objects when you pass in the corresponding user or course.

• For example, to load a course directory in the Blackboard Content System when the Blackboard Learning System blackboard.data.course object is present, run the following:CSDirectory courseDir = ctxCS.getCourseDirectory(theCourse);

Understanding Permissions and Principals • The access control system for files and folders in the Blackboard

Content System uses the concept of principals tied to permissions. • A “principal” is an entity with the base class of CSPrincipal. • This interface defines the concept of a principal, encompassing any

entity to which file system access permissions may be granted. • Every principal must be uniquely identified by a principal ID. • All Blackboard Content System user and group objects extend this

object. • These objects are found in the blackboard.cms.filesystem.security

package.

Understanding Permissions and Principals contd.• Subclasses of this include:

– CourseGroupPrincipal, CoursePrincipal, CourseRolePrincipal, PortalRolePrincipal, PortfolioPrincipal, SystemRolePrincipal, UserPrincipal.

– These encapsulate the primary ways people are associated with permissions.

• A look at one in more detail helps explain this concept. • If the goal was to give all Students in the “math10”

course the access control of “Read”– The developer would first use the above information to retrieve a

CSEntry with the desired file– …and then determine the CourseRolePrincipalID used to

represent the class of users associated in a course with the specific role.

Understanding Permissions and Principals contd.// Load the file

CSEntry csFileToChange = ctxCS.findEntry(“/user/dcane/foo.txt”);

// determine the principal ID

String strCourseRolePrincipal = CourseRolePrincipal.cacluatePrincipalID(courseMath101, courseRoleofStudent);

// get the Access Control Entry for that principal ID (even if it does not exist)

CSAccessControlEntry csACE = csFileToChange.getAccessControlEntry(strCourseRolePrincipal);

// then update the permission for “read”

csACE.updatePermission(true, false, false, false);

Request Utility Classes for Specific UI Hooks

• Content System Action Bar Building Blocks– You will want to get a list of the files/dirs selected on the previous page. – import blackboard.cms.servlet.CSActionRequest;– CSActionRequest actionReq = new CSActionRequest( request,

response, application );– List selectedFiles = actionReq.getSelectedPaths();

• Modify Content File/Folder Building Block – import blackboard.cms.servlet.CSModifyEntryRequest;– CSModifyEntryRequest modifyEntryReq = new

CSModifyEntryRequest( request );

• Manage Portfolio Building Block – import blackboard.cms.servlet.CSManagePortfolioRequest;– CSManagePortfolioRequest portfolioReq =– new CSManagePortfolioRequest( request );– Portfolio portfolio = portfolioReq.getPortfolio();

Blackboard Content System Changes for Packaging and Manifest File

• bb-manifest.xml– <csversion

• Element to define dependency on a specific Blackboard Content System version. The value has the same format as in the <bbversion> element. Not required.

– ifMissing>• Attribute of <csversion> element that determines whether the

package can be installed without the Content System present. Possible values are “fail” and “warn”. Not Required. Default value: warn.

Example of csversion in bb-manifest.xml <plugin>

<name value= "Sample Plugin"/>

<handle value= "plgnhndl"/>

<description value= "This plugin is a sample."/>

<version value= "1.0.0.1"/>

<requires>

<bbversion value="6.3.0"/>

<csversion value="2.3.0" ifMissing=”warn”>

</requires>

…

Example of UI Hooks in Blackboard Content System in bb-manifest.xml <!-- Tools defined by this extension --> <application-defs> <application handle="sampleapp" type="course" use-ssl="false" name="Sample Application" can-allow-guest="true" small-icon="" large-icon=""> <description lang="en_US">Application installed as part of the sample plugin</description> <links>

<link> <type value="cs_action"/> <name value="CS Action"/> <url value="actionbar.jsp"/> <description value="Sample CS Action Bar Plug-in"/> <icons></icons> </link> <link> <type value="cs_tool"/> <name value="CS Tool"/> <url value="tool.jsp"/> <description value="Sample CS Tool Plug-in"/> <icons></icons> </link> </links> …

Permissions Needed in bb-manifest.xml• Permissions you will need to set in

manifest:– <permission type="java.lang.RuntimePermission" name="db.connection.*" /> <permission type="attribute" name="user.authinfo" actions="get,set" /> <permission type="attribute" name="user.personalinfo" actions="get,set" /><permission type="persist" name="user" actions="create,modify,delete" /> <permission type="persist" name="userrole" actions="create,modify,delete" /><permission type="persist" name="course" actions="create,modify,delete" />

Closing Slide

• Innovating Together in ‘05:– This is just the beginning of what can be done! – We will be encouraging a community of practice around CS B2 development.

• Resources Available:– I listed a good slide about it– Email me!

• Follow up Contact(s):– Daniel Cane [ dcane@blackboard.com ] – Jan Day [ jday@blackboard.com ]

• IF YOU ONLY REMEMBER 1 THING:– Building using Building Blocks is easier than it looks. Just play around with the

stuff!