blackboard learn 9.1 - server administration

Server Administration

Blackboard Learn Release 9.1 - Server Administration - © 2011 Blackboard Inc. Proprietary and Confidential. U.S. Patent No. 6,988,138. Additional Patents Pending.

9.1 S

P6 BETA D

RAFT

Publication Date and Copyright NoticeBlackboard Learn™Help for Release 9.1 Service Pack 6 (SP 6) - BETA

Publication Date: May 12, 2011

Worldwide Headquarters International Headquarters

Blackboard Inc. Blackboard International B.V.

650 Massachusetts Avenue NWSixth FloorWashington, DC 20001-3796 USA

Paleisstraat 1-51012RB AmsterdamThe Netherlands

+1 800 424 9299 toll free US & Canada

+1 202 463 4860 telephone +31 (0) 20 788 2450 (NL) telephone

+1 202 463 4863 fax +31 (0) 20 788 2451 (NL) fax

www.blackboard.com www.blackboard.com

Copyright © 1997-2011. Blackboard Inc. All rights reserved. Blackboard, the Blackboard logo, BbWorld, andBlackboard product names are trademarks of Blackboard Inc. or its subsidiaries. Blackboard products may becovered by one or more of the following U.S. patents: 7,493,396, 7,558,853, 6,816,878.

Microsoft andWindows are registered trademarks of Microsoft Corporation in the United States and/or othercountries. Sun, Solaris, and Java are either registered trademarks or trademarks of SunMicrosystems, Inc. inthe United States and/or other countries. Oracle is a registered trademark of Oracle Corporation in the UnitedStates and/or other countries. Red Hat is a registered trademark of Red Hat, Inc. in the United States and/orother countries. Linux is a registered trademark of Linus Torvalds in the United States and/or other countries. Apache is a trademark of The Apache Software Foundation in the United States and/or other countries. RealPlayer and Real AudioMovie are trademarks of RealNetworks in the United States and/or other countries.Macromedia, Authorware, Shockwave, Adobe and Acrobat Reader are either registered trademarks ortrademarks of Adobe Systems Incorporated in the United States and/or other countries. Macintosh andQuickTime are registered trademarks of Apple Computer, Inc. in the United States and/or other countries.Crystal Reports is a trademark of Business Objects in the United States and/or other countries. WebEQ is atrademark of Design Science, Inc. in the United States and/or other countries. JSpell is a trademark of TheSolution Café in the United States and/or other countries.

Other product and company names mentioned herein may be the trademarks of their respective owners.

No part of the contents of this project may be reproduced or transmitted in any form or by any means withoutthe written permission of the publisher, Blackboard Inc.


9.1 S

P6 BETA D

RAFT

Contents

Server Administration 1Release 9.1 Information 16About Release 9.1 16

Skills Inventory 16

Project Management 16

Database Administration 16

System and Network Administration 17

Application Administration 17

Faculty Training 17

Help Desk Support 17

Instructional Design (Optional) 17

Programming (Optional) 17

Understanding the Change in Release 9.1 18

Blackboard Learn 18

Academic Suite 18

CE 4 18

CE 8 18

Vista 8 18

System Planning 19Getting Started with Server Administration 19

Where to Start 19

Other Resources for Administrators 19

PushConfigUpdates 19

Blackboard Learn - Basic Edition Limitations 19

Strategic Planning 20

Questions to Ask Prior to Integration 20

Project Teams 20

Steps to a Successful Integration 20

Data Integration Planning Process 21

Tips 21

Planning Through Standardization 21

Standardized Structures 21

Virtualizing the Blackboard Reference Architecture 22

Supported Virtualization Technologies 22

Benefits of Virtualization 22

Load Balancer Guidelines 23

Port Requirements 23


9.1 S

P6 BETA D

RAFT

Identifying the Server for Troubleshooting Purposes 23

Persistence Requirements 23

Health Check 23

Health Check Interval 23

Idle Timeout 24

DistributionMethods 24

Collaboration Server 24

Blackboard System Tasks 25

Service Pack and Security PatchMaintenance 26

How to Apply a Service Pack or Security Patch after Installing Blackboard Learn 26

Configuration Changes 27

How toMake Changes to the System Configuration 27

Hardware Sizing Information forWindows Dell Environments 27

About Hardware Sizing in a Dell Environment 27

SizingMethodology for Dell 28

Recommended Configurations for Dell 29

Deploying Blackboard Learn for Dell 29

Virtualizing at the Application Layer for Dell 30

Sizing the Application Server for Dell 30

Sizing the Database for Dell 33

Sizing Storage for Dell 34

Blackboard Learn Release 9.1 Configurations for Dell 36

Hardware Sizing Information for UNIX Sun Environments 38

About Hardware Sizing in a SunMicrosystems Environment 38

SizingMethodology for Sun 39

Recommended Configurations for Sun 39

Deploying Blackboard Learn for Sun 40

Sizing the Application Server for Sun 40

Sizing the Database for Sun 41

Sizing Storage for Sun 42

Blackboard Learn Release 9.1 Configurations for Sun 44

Architecture 46

About the File System 46

Setting Up the Content Collection 47

Setting Up Tomcat Clusters 49

Setting Up LDAP 54

Setting Up a Proxy Server 55

Using Services 55

Glossary of Terms 57


9.1 S

P6 BETA D

RAFT

About the Installation Process 60Fresh Installations 60

Upgrades 60

Getting Started 60

About the Installation Process 60

Preferred Technical Skills 60

About the Blackboard Learn Installer and Updater 62

Understanding the Database Schema 63

Understanding Load Balancing 64

Defining the Host Environment 65

Planning the Installation 68

Windows 69

Install onWindows onOne or Two Servers 69

Install onWindows in a Load-Balanced Configuration 84

TroubleshootingWindows Installation 105

UNIX 107

Install on UNIX onOne or Two Servers 107

Install on UNIX in a Load-Balanced Configuration 118

Troubleshooting UNIX Installation 133

Uninstalling Blackboard Learn 134

Before Running the Uninstaller on UNIX 134

Uninstalling on a Load-Balanced System 134

How to Uninstall Blackboard Learn 135

Upgrades 136About Upgrading to Release 9.1 136

Prepare for the Upgrade 136

Perform the Upgrade 136

After the Upgrade 136

Understanding the Change in Release 9.1 136

Blackboard Learn 136

Academic Suite 136

CE 4 137

CE 8 137

Vista 8 137

Running the Pre-Update Change Report 137

How to Run the Pre-Update Change Report onWindows 137

How to Run the Pre-Update Change Report on UNIX 137

Release 9.0 to 9.1 138

Windows 138


9.1 S

P6 BETA D

RAFT

UNIX 143

Release 8 to 9.1 148

Windows 148

UNIX 152

CE 4 to Learn 9.1 157

Before You Begin 157

Understanding the Process 158

Step 1: Install Blackboard Learn 159

Step 2: Export All Data from CE 4 159

Step 3: Import CE 4 User Data into Blackboard Learn 160

Step 4: Export Course Content Packages from CE 4 161

Step 5: Import CE 4 Courses into Blackboard Learn 162

Step 6: Import CE 4 Enrollments into Blackboard Learn 164

Data Source Keys 165

LMSImport Switches for CE 4 166

CE 8 to Learn 9.1 168




Step 2: Export All Data from CE 8 170

Step 3: Import CE 8 User Data into Blackboard Learn 171

Step 4: Export Section Content Packages from CE 8 172

Step 5: Import CE 8 Sections into Blackboard Learn as Courses 173

Step 6: Import CE 8 Enrollments into Blackboard Learn 175


LMSImport Switches for CE 8 177

Vista 8 to Learn 9.1 179




Step 2: Export All Data from Vista 8 181

Step 3: Import Vista 8 User Data into Blackboard Learn 182

Step 4: Export Section Content Packages from Vista 8 183

Step 5: Import Vista 8 Sections into Blackboard Learn as Courses 184

Step 6: Import Vista 8 Enrollments into Blackboard Learn 187


LMSImport Switches for Vista 8 189

Upgrading the Blackboard Learn LicenseOnly 190

How to Upgrade the Blackboard Learn License 191


9.1 S

P6 BETA D

RAFT

Databases 192About the Databases 192

BBLEARN_ADMIN 192

BBLEARN 192

BBLEARN_STATS 192

Database Users 192

Database Schema Legacy Information and Document Stores 193

Database SchemaNaming 193

Starting Services in a SQL Environment 193

How to Start Services 193

How to Stop the Services 193

Starting Services in anOracle Environment 193

How to Start Services 193

Oracle RAC Support on UNIX 194

Configuration 194

Prerequisites 194

How to Configure the Oracle RAC Environment 194

How to Configure Single InstanceMode 195

How to Upgrade Blackboard Learn in anOracle RAC Environment 196

Special RAC Patches onOracle RAC 196

Best Practices 197

Installing and Upgrading Small Scale Oracle 197

About Small-Scale Oracle 197

Installing Small Scale Oracle 10g 197

Upgrading Small Scale Oracle 9i to 10 204

Uninstalling Small Scale Oracle 206

Authentication 207Using Blackboard Learn Authentication 207

Customize the Default Authentication 207

Return to the Default Authentication 207

Authentication Properties 207

About Authentication Object Models 208

Authentication Object Model 208

Planning Authentication Implementation 208

Blackboard Default Implementation 208

LDAP Implementation 209

Web Server Delegation Implementation 209

Extending Other Blackboard-created AuthenticationModules 209

Sample Custom AuthenticationModule 209


9.1 S

P6 BETA D

RAFT

Sample IUserPassAuthModule Code 213

About Active Directory Authentication 213

Active Directory Authentication 213

Security Considerations 214

Limitations 214

Active Directory Authentication and Portal Direct Entry 214

Setting Up Active Directory 214

File Format 214

How to Set the Authentication Type 214

Active Directory Property Configuration 215

Example 215

About the LDAP AuthenticationModule 216

Limitations 216

LDAP Authentication 216

Setting Up LDAP Authentication Properties 216

File Format 216

How to Edit the Authentication Properties File 217

LDAP Property Configuration 217

Example 218

Using LDAP Authentication Fail Over 219

Automatic Fail Over for LDAP Server Error 220

Automatic Fail Over for Users who DoNot Exist in LDAP Database 220

Security Considerations 220

How to Enable Authentication Fail Over for LDAP Server Error 220

How to Enable Authentication Fail Over for Users who DoNot Exist in LDAP Database 220

Using LDAP with Active Directory 221

Connecting via an Anonymous Bind 221

How to Enable Anonymous Searches on the Active Directory Server 221

Connecting via a Privileged Bind 221

Troubleshooting LDAP with Active Directory 221

Troubleshooting LDAP 222

How to Debug LDAP Authentication 222

Troubleshooting LDAP Authentication Properties forWindows 222

Troubleshooting LDAP Authentication Properties for UNIX 223

How to Revert to Default Authentication 224

Blackboard Application Log 224

Common Problems 224

LDAP Scenarios 224

How to Troubleshoot LDAP with SSL 225


9.1 S

P6 BETA D

RAFT

About Web Server Delegation Authentication 227

Management 227

Implementation 228

Web Server Delegation withWindows 2003 228

How to ConfigureWeb Server Delegation withWindows 2003 228

About Custom Authentication 229

Audience 229

DataModel 229

Setting Up and Deploying Custom Implementations 229

Extending Blackboard-provided Implementations 229

Extending the Blackboard Default Implementation 230

Creating a Custom LDAP Implementation 230

Creating a CustomWeb Server Delegation Implementation 231

Deploying Custom Implementations 231

Updating the Collaboration Server 231

Updating the launch-tool Script 232

UsingWebDAV with a Custom Implementation 232

Troubleshooting Custom Implementations 232

Setting UpCustomized Authentication Page Flow 232

Implementing requestAuthenticate() 233

Redirecting to the Original Target URL 233

About Authentication through the API 233

Authentication ProcessingMethods 233

Configuration File ProcessingMethods 236

Using Servlet Authentication 237

Login 237

Logout 238

SSL 239About SSL and SSLChoice 239

How Does SSLWork? 239

How to Obtain a Certificate 239

How Does SSL Appear to Users? 240

SSLChoice 240

Setting Up SSL for IIS 240

How to Configure SSL for IIS 240

Setting Up SSL for Apache 241

How to Configure SSL for Apache 241

Setting Up SSLChoice 242

How to Set Up SSLChoice 242


9.1 S

P6 BETA D

RAFT

Setting Up LDAP Authentication with SSL 243

How to Configure LDAP Authentication with SSL for the JAVA Runtime Environment (JRE) 244

How to Configure Contextual Error Messages for LDAP 244

Setting Up SSL for SIF 244

Creating and Configuring the Keystore 245

Configuring TrustStore 246

Setting Up SSL for the Collaboration Tool inWindows 247

How to Configure the Collaboration Tool with a Self-signed Certificate 247

Load-Balanced Configurations 247

How to Create the Keystore 247

How to Configure Tomcat toWork with the SSLCertificate 248

Setting Up SSL for the Collaboration Tool in UNIX 248

How to Configure the Collaboration Tool with a Self-signed Certificate 249

How to Configure the Collaboration Tool with a Signed Certificate 249

How to Create the Keystore 249

How to Configure Tomcat toWork with the SSLCertificate 250

SIF 251About SIF 251

Exchanging and Synchronizing Data 251

The Blackboard SIF Agent 251

Setting Up the Blackboard SIF Agent 251

How to Edit the service-config.properties File 252

How to Configure Settings in the bb-config.properties File 252

Sample bb-sif-agent-config.xml File 254

Using DataMapping 254

API 256About the Event Driven API Architecture 256

Entities and Persisters 256

Operations 256

How to Create anObject 256

Persisters 256

Loaders 257

Data Source Loader and Persister 257

About Event Driven APIs 257

Using the API and Determining Relationships 258

How to Determine Relationships 258

About the Persister Package 260

Persistence Package 260

Tools 261


9.1 S

P6 BETA D

RAFT

Using Command Line Tools 261

PurgeAccumulator 261

PushConfigUpdates 261

RotateLogs 262

ServiceController 262

SystemInfo 263

Using Command Line Tools with Content 263

Using Spaces in Directory Names 264

file-import 264

create-all-user-directories 264

create-directory 265

create-user-directory 265

create-course-directory 265

set-directory-quota 266

user-access-control 266

course-access-control 266

course-role-access-control 267

full-text-index UPDATE 267

full-text-index UNLOCK 267

Copy Files to CS Tool 267

create-all-user-directories 268

Data SourceManagement (DSM) Tool 268

About Data Entities 268

About the Data Package 269

About Data SourceManagement and Data Source Keys 270

About Data Source Keys 271

About Data SourceManagement 271

About the DSM Tool 272

DSM Tool Syntax and Commands 272

Snapshot Tool 274

Strategic Planning 274

Planning Frequency of Snapshot Data Feeds 276

Planning Through Standardization 276

Snapshot Use Cases 277

About the Snapshot Tool 279

About the Snapshot Tool Workflow 279

Data Life Cycle Planning 280

Data States 281

The Data Life Cycle and Triggering Events 283


9.1 S

P6 BETA D

RAFT

Data Operations Planning 285

Using Snapshot Modes 287

Setting Up the Snapshot Tool Service 289

Using the Properties File 290

Syntax for the Snapshot Tool 293

Using Operational Commands for Snapshot Modes 294

Snapshot OverrideMode 296

Setting Up SOAP for Use with the API 296

DataMapping 298

About Snapshot Automation 298

Process Diagram for Automation 299

About the Snapshot Properties File 300

About Feed Files 300

Using Delimiters and Escape Characters 300

Using the Snapshot XML Feed File Format 301

Using the Snapshot Flat Feed File Format 302

Setting Up Integration Tools on a Client Machine 304

Backup and Recovery 306Windows 306

About Backup and Recovery 306

Resource Planning 307

About Moving Blackboard Learn in a SQL Environment 309

Moving Content Management Files 309

Backing up the Database in a SQL Environment 310

Setting Up Target System in a SQL Environment 312

Editing the Properties File in a SQL Environment 314

Restoring the Database in a SQL Environment 315

UNIX 321

About Backup and Recovery 321

Resource Planning 322

About Moving Blackboard Learn in anOracle Environment 324

Moving Content Management Files 325

Exporting the Database in anOracle Environment 325

Setting Up Target System for Import in anOracle Environment 326

Importing the Database in anOracle Environment 327

Editing the Properties File in anOracle Environment 330

Performance Optimization 332About Optimizing Blackboard Learn 332

Optimizing Performance 333


9.1 S

P6 BETA D

RAFT

Optimizing Application Tier Performance 333

Optimizing Database Tier Performance 334

Optimizing AddressableMemory Using 64-Bit Deployments 334

Apache 334

Configuring Apache HTTP Server 334

Using the Server-Status Module for Apache 335

Measuring Interface Performance 336

IIS 337

ConfiguringMicrosoft IIS 337

Monitoring Performance Counters 337

Monitoring Threads 338

Throttling Connection Sizes 338

Tomcat 338

Using Tomcat Clusters 338

Configuring Database Connections 339

Sizing theMaximum Thread Count 340

Sizing the JavaObject Heap 341

Using Non-Standard (-XX) JVM Arguments 342

Understanding the Regions of the Java Heap 342

Configuring Ehcache 343

Setting the cache-settings.properties Parameters 343

Understanding the bbconfig.cache Parameters 343

Performance Settings 345

Document Store Settings 345

Enabling Tomcat ThreadQueuing 346

Installing One orMore Tomcat Clusters 348

Troubleshooting Installation Issues 351

Enabling Cache Replication 351

Removing a Cluster Node 352

SQL 352

Pre-Installation Recommendations in a SQL Environment 352

Pre-Allocating LUNs in SQL 353

Configuring the Paging File 353

Configuring SQL Server Settings 354

Configuring READ_COMMITTED_SNAPSHOT Isolation Level 354

Working with the TEMPDB in a SQL Environment 355

Using the SQL 2005 Server Performance Dashboard 355

TrackingWait Events andQueues 356

Monitoring Key Areas 356


9.1 S

P6 BETA D

RAFT

Oracle 357

Pre-Installation Recommendations in anOracle Environment 357

Configuring the Storage Configuration 357

ForecastingMemory Utilization 358

Sizing the System Global Area 358

Sizing the Program Global Area 359

Configuring Temporary Tablespaces 360

Configuring the REDOTablespace 360

Configuring the UNDOTablespace 361

Setting Oracle Initialization Parameters 361

Understanding the Importance of Optimizer Statistics 361

Using the OracleWait Interface 362

Document Store Settings 362

How to Edit the Content Management Document Store Settings 362

bb-config.properties File 363

How to Edit the bb-config.properties File 363

Recommended JVM Tuning Set 367

Related Resources 367

Apache HTTP Server for UNIX 367

Microsoft IIS forWindows 367

Apache Tomcat Application Container 368

Microsoft SQL Server 368

Oracle Database 369

Resources 370Elements 370

Category Data Feed Elements 370

Category Membership Data Feed Elements 371

Course andOrganization Data Feed Elements 371

Enrollment and Staff Students Data Feed Elements 374

Observer Association Feed Elements 376

User Data Feed Elements 376

User Institution RoleMembership Data Feed Elements 380

XML 380

Samples 392

Sample Code for Clean Up of Database BoundObjects 392

Sample Code to Create Data Objects 393

Sample Code for Data Object AttributeMarshalling 394

Sample Code to Start Course/Organization Copy Testing 395

Sample Code to Start Persistence Testing 396


9.1 S

P6 BETA D

RAFT

Sample Naming Convention for Data Source Keys 408

Sample Properties File 409

Sample XML Feed File 411


9.1 S

P6 BETA D

RAFT

Release 9.1 Information > About Release 9.1

Release 9.1 Information

About Release 9.1Before working with any release, make sure to read the Release Notes for the release that you are installingand any subsequent Service Packs.

If you are upgrading to Blackboard Learn Release 9.1, make sure to read the Understanding the Changeinformation relevant to your current installation.

Skills InventoryBecause Blackboard Learn deployments vary widely in size and scope, there is not just one formula for thecomposition of an implementation team on campus. In many cases, a single individual may play multiple roles.

To prepare for Blackboard Learn, make sure that you have a team with skills that cover the key areas listed inthis topic.

Should you find, after evaluating your team against these recommended skill sets, that you need help in any ofthese areas, please consider Blackboard services including Consulting, Training, and BlackboardManagedHosting. These Blackboard services teams are capable of providing information and training to complement theskills your team already has and equip them to domore. You can learnmore about these services by talkingwith your account team or visiting www.blackboard.com.

Project ManagementResponsibilities:

l Manage overall project schedulel Deliverablesl Budgetl Resources

Skills Required:

l IT implementationl Changemanagement experience

Database AdministrationResponsibilities: Manage the database for Blackboard Learn, including:

l Backup and restorel Server/database instancemonitoringl Space/memory managementl Security planl Upgrades

Skills Required:

l Experience acting as DBA for production Oracle® orMicrosoft® SQL Server instancesl Production experience in the use of monitoring and backup utilities deployed at the institution


9.1 S

P6 BETA D

RAFT

http://kb.blackboard.com/display/DOCS/Blackboard+Maintenance+Center


http://www.blackboard.com/

Release 9.1 Information > Skills Inventory

l Platform specific OS administration knowledge

System and Network AdministrationResponsibilities: Administer Blackboard Learn and the supporting system infrastructure, including:

l Operating system software on application server(s) and database serverl Network infrastructure (switches, routers, firewalls, etc.)l System and Blackboard Learn Release 9 securityl Performancemonitoring and tuning

Skills Required: Intermediate-level system administrator with expertise in TCP/IP networking and experiencewith OS platform

Application AdministrationResponsibilities: Manage Blackboard Learn, including:

l Performing administration tasks via the GUIl Designing and executing start/end of term activities

Skills Required: Blackboard Learn administration, including user management and roles, content management,application configuration, and settings.

Faculty TrainingResponsibilities: Provide training for faculty and staff on product functionality and use.

Skills Required: Blackboard Learn designer and instructor; training development and delivery.

Help Desk SupportResponsibilities: Provide support on application functionality and tool use to faculty, staff, and students.

Skills Required: Expertise in Blackboard Learn, including end-user, customer service, and knowledge ofescalation processes; Familiarity with resources available on Behind the Blackboard

Instructional Design (Optional)Responsibilities: Assist faculty with the development of courses. Help develop and design exemplary onlinecourses using best practices that are pedagogically sound and promote the course’s goals and objectives

Skills Required: Blackboard Learn designer and instructor, instructional design competency, andWebdevelopment skills

Programming (Optional)Responsibilities: Execute integration between Blackboard Learn and your student information system, portal,authentication system, etc.

Skills Required: Programming expertise in Java/Perl or Visual Basic, or C++ and XML, as well as familiaritywith involved products.


9.1 S

P6 BETA D

RAFT

Release 9.1 Information > Understanding the Change in Release 9.1

Understanding the Change in Release 9.1If upgrading from a previous product release or from a legacy product such as CE 8, the “Understanding theChange” document for each product release gives users a comprehensive look at the features and functions ofthis release and how they compare to the user’s current product release. Quick Reference documents are alsoavailable for Instructors and Administrators moving from CE 4, CE 8, or Vista 8.

These documents are available on the Blackboard Upgrade Center or Behind the Blackboard.

Blackboard LearnUnderstanding the Change from Learn 9.0

Blackboard Learn 9.1 Service Pack 1: Enhancements

Blackboard Learn 9.1 Service Pack 1: Enhancements in Outcomes Assessments

Academic SuiteUnderstanding the Change from Academic Suite

CE 4Understanding the Change from CE 4

Understanding the Change from CE 4 - Quick Reference for Administrators

Understanding the Change from CE 4 - Quick Reference for Instructors


Quick Reference for Administrators

Quick Reference for Instructors

Vista 8Understanding the Change from Vista 8




9.1 S

P6 BETA D

RAFT

http://www.blackboard.com/Sites/UpgradeCenter/



https://behind.blackboard.com/



http://library.blackboard.com/d/?78dbe3fc-1c0d-4f66-8946-bac91d2a3db7






http://library.blackboard.com/d?e6761ad5-9510-472a-980d-d66426c1de48







http://library.blackboard.com/d?864b1463-bd8d-4aaa-afef-19560c650b75










http://library.blackboard.com/d/?2e828f85-5bf5-4a94-b1f7-9e367ee9ebab






http://library.blackboard.com/d?ed9ad851-ceb4-4ba4-90b2-1814ba314185






http://library.blackboard.com/d?a3e1fcb5-5abd-4f8b-819f-76592fc8956a











http://library.blackboard.com/d?1bfe7435-5bf2-4961-a56b-259b8c9d18c9











http://library.blackboard.com/d?2aedaf76-c769-4a26-a411-4bf55d4ed899






http://library.blackboard.com/d?65ff84c7-d4ac-4a4e-ab5a-59e09cc2d043




http://library.blackboard.com/d?a7a5da60-482a-4cb5-a6a3-62a78562aa98




http://library.blackboard.com/d?00510c89-ff47-4ac7-aab4-4c00f3fe9445






http://library.blackboard.com/d?4da78ba9-c06e-40cd-b9ea-d82c6b9c1630




http://library.blackboard.com/d?08ba8687-2160-4166-9da7-1c148bcf470a




System Planning > Getting Started with Server Administration

System Planning

Getting Started with Server Administration

Where to StartInstitutions that have just installed Blackboard Learn should become familiar with the environment beforemaking it available to users. After installation, read the available Blackboard Learn documentation and thendevelop and revise a plan for managing the system. Consider:

l Authentication: Should users login to Blackboard Learn using a unique user name and password orshould users authenticate once on the network and then have seamless access to Blackboard Learn?Read the section on Authentication for information on how to integrate Blackboard Learn with anauthentication system already on campus (such as LDAP or Active Directory).

l Security: Should user communications with Blackboard Learn be protected by SSL?Will users sufferwith slower performance due to SSL? Read the section on SSL to encrypt user communications withBlackboard Learn.

l Maintenance: Read the Blackboard Learn Architecture section for guidance on server maintenance.This section also reviews the file system and database structure and the command line toolsavailable to administrators.

Other Resources for AdministratorsIt is important that administrators read the in the Release Notes for the release that you are installing andreview the Known Issues and Resolved Issues.

For information about optimizing Blackboard Learn to perform best in a particular environment, see AboutOptimizing Blackboard Learn.

PushConfigUpdatesThe PushConfigUpdates command automatically updates the admin data in the database by reading thevalue in the config.xml. It automatically pushes the changes of the database hostname and port, instancename, and externally visible web server hostname to the database.

When the PushConfiguUpdates command is complete, it will not display whether or not dynamiccompression is enabled on your IIS installation. Verify this setting in IIS 6.0 by visiting Configure Compressionin IIS 6.0 usingWindows 2003 or in IIS 7.0 by visiting Configure Compression in IIS 7.0 usingWindows 2008.

To learnmore about PushConfigUpdates, see PushConfigUpdates.

Blackboard Learn - Basic Edition LimitationsSeveral of the server-side options described in this manual are not available to Institutions running BlackboardLearn - Basic Edition. Blackboard Learn - Basic Edition administrators will find the Architecture sectionvaluable. Integrated authentication and SSL are not available with Blackboard Learn - Basic Edition.


9.1 S

P6 BETA D

RAFT







http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/92f627a8-4ec3-480c-b0be-59a561091597.mspx








http://technet.microsoft.com/en-us/library/cc753681(WS.10).aspx








../../../../../Content/Mini_TOCs/mt_admin_server_plan_arch.htm

System Planning > Strategic Planning

Strategic PlanningImporting user, Course, enrollment, and staff data from an institution’s information systems into BlackboardLearn can involvemany different systems and different people. Blackboard Learn is installed with the tools toassist with this process, but every Organization is unique and has different requirements.

To establish a successful process, careful planning is necessary as well as an understanding of the underlyingsystems involved. The integration process is a collaborative effort between Blackboard Learn and theinstitution. Working together to design and then implement a seamless process takes considerable planning.Blackboard Consulting can provide the support, experience, and knowledge necessary to assist institutionswith an efficient integration.

Questions to Ask Prior to IntegrationInstitutions must answer the following questions prior to data integration:

l Which institutional systems contain the data for integration with Blackboard Learn?l How will attributes of the institutional systemmap to Blackboard Learn?l Which criteria must be satisfied before a data record can be sent from the institutional system to

Blackboard Learn?l How will integration provide the needed packaging and error handling practices required by the

institution?

Project TeamsTo successfully plan and implement a data integration project, Blackboard recommends forming cross-functional teams representing each stakeholder in the project. These teams usually consist of:

l An institutional Project Managerl Analysts with detailed understanding of the institution’s business processes, needs, and associated

information systemsl Programmers with the ability to query, report from, and interface with the enterprise systems

If the institution is working with Blackboard Consulting on the data integration project, these teams should alsorepresent Blackboard, the institution, and solution partners. These teams may consist of:

l An institutional Project Managerl A Blackboard Project Managerl Institutional analysts with detailed understanding of the institution’s business processes, needs, and

associated information systemsl Institutional programmers with the ability to query, report from, and interface with the enterprise

systemsl Blackboard and solution-partner technical consultants

Steps to a Successful IntegrationThere are seven basic steps to a successful integration.

1. Define the scope and time frame of the data integration project: what data entities will beexchanged between the systems and when will the project be complete?


9.1 S

P6 BETA D

RAFT

System Planning > Planning Through Standardization

2. Develop, analyze, and document requirements, including ownership of data entities and attributes,key definition, attributemapping, datamodeling and trigger determination, timeliness, reliability,security, and operational issues.

3. Design, configure, and program a data-integration solution: although Blackboard Learn featuresmany built-in integration capabilities, some institutions may require additional customization.Where appropriate, the project team can use existing solutions from enterprise vendors, reuse priorsolutions developed for other institutions, or develop an entirely new custom solution.

4. Develop and document operating procedures for all affected parties.5. Test the system.6. Transfer the technology to the operations team at the institution.7. Train all relevant personnel.

Data Integration Planning ProcessDocument the planning, design, configuration and programming of the data integration process of steps two andthree in the previous list. The planning portion consists of developing the following:

l Data mapping: organize the data sources to prepare the data dictionary (a document that lists thevarious acceptable attributes for each data field) andmap required and optional attributes ofBlackboard Learn to those of institutional systems. The Blackboard Data Dictionary begins withCategory Data Feed Elements.

l Data lifecycle: generate business rules that regulate how data is handled, for example when recordsare added, removed or archived.

l Data operations: generate rules that govern the use of the integration tools to transfer data, forexample how the system is initially populated, and how it is synchronized with other systems.

Tipsl Complete the data integration for one information system at a time; it is quicker to add a second

auxiliary system after the first is done.l When planning the integration, focus on getting the data into the system before determining when to

remove it. In most cases, institutions will have a whole semester or longer to complete the rules fordisabling data so the plan to remove it does not have to be completed up front.

l For assistance in planning data integration, please contact Blackboard Consulting.

Planning Through StandardizationFor systems to be able to exchange data, standardized structures need to be in place. The informationmodelused by Blackboard Learn is that defined by the Instructional Management System (IMS) consortium. IMS is aglobal effort whose primary objective is to define a standardized set of structures that can be used to exchangedata between different instruction-based systems. IMS has defined an informationmodel and provided aspecification for transfer of such data.

To learnmore, visit the IMSWeb site: http://www.imsproject.org/.

Standardized StructuresThe structures within Blackboard Learn that are standardized to use the IMS model for exchanging data allowfor the successful mapping of an institution’s data into Blackboard Learn. The following table details these


9.1 S

P6 BETA D

RAFT

http://www.imsproject.org/

System Planning > Virtualizing the Blackboard Reference Architecture

structures.

BlackboardLearn DataEntity

IMS DataEntity Description

User Person An end user of Blackboard Learn, including Students, staff, and others.

Course Group An instance of an online class delivered through the Blackboard Learn, typically aCourse section.

Organization Group A site for groups, Organizations, clubs, and teams to have an online presence,share information, engage in increased communication, and collaborate on tasks.

Studentenrollment

Groupmembership

The record establishing a Student’s participation in a Course Web site.

Staff Student Groupmembership

The record establishing a staff member’s participation in a Course Web site andtheir role in the delivery of the course.

Organizationmembership

Groupmembership

The record establishing a user’s membership in an Organization and their role inthe organization.

Virtualizing the Blackboard Reference ArchitectureVirtualization is a deployment strategy that distributes server resources into separate, logical environments.When systems are virtualized, a layer of software is abstracted so that more than one operating system andapplication environment can operate on the same piece of hardware. Multiple virtual machines (VMs) sharehardware resources without interfering with each other.

The Blackboard Reference Architecture extends virtualization tomake the best use of today’s powerfulhardware. As organizations add hardware to their systems with multiple processors andmultiple cores perprocessor, virtualizing those systems is the next logical step in maximizing the potential and efficiency of theseresources.

Blackboard encourages the use of virtualization as an extension of the Blackboard Reference Architecture. Thecreation, maintenance, and troubleshooting of the VM environment is the responsibility of the client.

Supported Virtualization TechnologiesVMware® ESX Server 4 (Linux® andWindows®) is the only configuration Certified by Blackboard for Release9.1.

Blackboard supports other virtualization solutions as long as Blackboard and the hypervisor support the guestoperating system.

In addition to VMware, Blackboard has experience with Solaris™ 10 Zones and Red Hat® Enterprise Linux® 4& 5 Xen™.

Benefits of VirtualizationThemain benefits of virtualization are:

l Save Money: Virtualized systems reduce overall hardware costs because the hardware can be usedmore efficiently. Using fewer servers means there is less supporting physical infrastructure. Theresult is less power drawn to run hardware and lower cooling requirements. This allows organizations


9.1 S

P6 BETA D

RAFT

System Planning > Load Balancer Guidelines

the flexibility to expand their IT infrastructure at an appropriate pace.l Save the Environment: Reducing the number of servers in a datacenter reduces the energy footprint

of the implementation. Fewer servers require less floor space, air conditioning, racks, networks, wire,cables, power supplies, and backup systems. The cost savings can be significant when adding upthe amount for the servers, themonitors, and the air conditioning required for keeping them cool.

l Achieve Higher Levels of Availability/ Business Continuity: Virtualizationminimizes serverdowntime. A crash can occur within a VM and not impact the other VMs on the same server. Thisallows an organization to shut down individual VMs without interfering with the use of otherapplications. VMs can save hours of downtime related to recovery to general maintenance. Theability to move servers between hardware can simplify upgrades.

Load Balancer GuidelinesBlackboard supports load balancing across application servers but does not support any specific hardware loadbalancer. These general recommendations can be used to configure your load balancer of choice to work bestin your particular environment.

Note: SSL off-loading is not supported by Blackboard.

Port RequirementsUse the following ports when configuring your system:

l HTTP: 80l HTTPS: 443l Collaboration Server: 8010 and 8011 (Optional: 8443 if the Collaboration Server is using SSL)

Identifying the Server for Troubleshooting PurposesFor each server, create a static server.html page that displays its identifying information. Place all of the pagesin the /blackboard/docs directory. To view the server.html page for the current server, go to the following URL:http://blackboard.yourschool.edu/server.html.

Persistence RequirementsBlackboard recommends configuring the load balancer for cookie-insert-based session affinity. The Blackboardsession cookie should be used only as an alternative to the cookie-insert method.

Health CheckBlackboard recommends monitoring Tomcat, Apache (Linux), and IIS (Windows) for liveliness to ensure thatthe load balancer is sending traffic to application servers that are able to handle the traffic.

Health Check IntervalWhen performing a health check, it is important to set a health check interval that is frequent enough tomaintain the health of the application, but not so frequent that it affects performance. When a health check failsfor a specific application server, the load balancer redistributes the traffic that was bound for that server to theremaining available servers. This interval should be optimized to ensure that healthy nodes do not inadvertentlyfail the health check during a full garbage collection by the JVM. Blackboard considers intervals such as one


9.1 S

P6 BETA D

RAFT


minute or .1 seconds as extreme values and recommends that they be avoided. Blackboard recommendsstarting with a health check interval of 20 seconds and blocking traffic to a node after three failures (60seconds).

Idle TimeoutBlackboard recommends that a browser session cookie be inserted at the load balancer so that the sessioncookie does not time out until the user closes their browser. The idle timeout of the persistence cookie insertedat the load balancer should be set to greater than the Blackboard session timeout.

Distribution MethodsDifferent algorithms can be used to determine distributionmethods. “Round robin” and “least connections” arethe twomost common load balancingmethods used. To avoid overloading any single server in the cluster,select themethod that will ensure that each application server receives approximately the same amount oftraffic.

Collaboration ServerThe Collaboration Server is a standalone service that provides chat and virtual classroom services. Only oneCollaboration Server can be available in an environment. Attempting to load balancemultiple CollaborationServers will result in users being isolated from each other on different servers. When configuring your loadbalanced environment, youmust choose one Blackboard application server to also run the CollaborationServer.

Standard Collaboration Server ConfigurationIn the standard configuration, the Collaboration Server can be connected to directly through an externalhostname.

How to Use the Standard Configuration1. On each Blackboard Learn application server, set the following parameters in the bb-

config.properties file:a. Set bbconfig.config.collabserver.fullhostname.default to the fully

qualified hostname of the Collaboration Server.b. Set bbconfig.collabserver.run.on.localhost to false.

2. On the Collaboration Server, in the bb-config.properties file, setbbconfig.collabserver.run.on.localhost to true.

Alternate Collaboration Server ConfigurationAlternatively, the Collaboration Server can be configured to be available through the load balancer. This can beuseful because the standard configurationmight make it necessary to change IP configurations or wait for DNSupdates in the event of a host failure.

Note: In the event of a Collaboration Service failover to another host, all existing sessions will be lost.


9.1 S

P6 BETA D

RAFT


How to Use the Alternate Configuration1. On the load balancer, configure the Collaboration Server to be available on ports 8010 and 8011 as

IP layer 4 services.2. On each Blackboard Learn application server, set the following parameters in the bb-

config.properties file:a. Set bbconfig.config.collabserver.fullhostname.default to the fully

qualified hostname of the Blackboard load balanced address.b. Set bbconfig.collabserver.run.on.localhost to false.

3. On the Collaboration Server, in the bb-config.properties file, setbbconfig.collabserver.run.on.localhost to true.

Blackboard System TasksCertain Blackboard system tasks need to be executed on only one server, while other tasks need to beexecuted on all servers. These tasks are outlined and configured in the blackboard/config/bb-tasks.xml file.

On All Application ServersThe following tasks must be run on each application server:

l bb.db.cache

l bb.task.queue

l bb.systeminfo.reporting

l bb.portal.integration.poolmanagementstartup

On One Application ServerThe following system tasks need to be run on one application server to optimize performance:

l bb-db.cache

l bb.portal.channel.update

l bb.scheduled.report.queuer

l bb.cartridge.download

l bb.portal.emailnotification

l bb.session.invalidation

l bb.disk_usage

l bb.portal.includeUrl.update

l bb.stats.purging

l bb.distribution.sendnotification

l bb.portal.integration.poolmanagementstartup

l bb.systeminfo.reporting

l bb.domain.calculation

l bb.quota.notification

l bb.task.queue

l bb.ew.refresh.all.rules

l bb.remove.stale.notification.data


9.1 S

P6 BETA D

RAFT

System Planning > Service Pack and Security Patch Maintenance

l bb.tracking.report

l bb.log.rotation

l bb.scheduled.workflow.queuer

l bb.remove.stale.notification.data

l bb.distribution.sendnotification

l bb.ews.refresh.all.rules

Note: The bb-task.xml file will be reset to its default settings when you install any Blackboard Learn softwarepatch or upgrade. Youmust make the desired changes to this file after every software patch or upgrade.

Service Pack and Security Patch MaintenanceBlackboard supports operating system and database service packs and security patches for the operatingsystems and databases supported for use with Blackboard Learn, and Blackboard Learn - Basic Edition.Blackboard will test, certify, and, if necessary, provide fixes to ensure that Blackboard systems work withservice packs and security patches.

There is, necessarily, a short lag time between a service pack release and the completion of testing. Evenduring this interim testing period, however, Blackboard will provide support for just released operating systemand database service packs and security patches.

Note: This policy does not include support for subsequent releases. For example, if Blackboard supportsversion 1 of a database system any security patches or service packs for version 1 will be supported.

Blackboard will not support a version 2 release of the same database system until that version has beenproperly tested and published as part of the software requirements for that release of the Blackboard system.

How to Apply a Service Pack or Security Patch after Installing BlackboardLearn

1. Back up the system.2. Shut down Blackboard Learn.3. Contact Blackboard Technical Support by logging in to Behind the Blackboard at

https://behind.blackboard.com to check for any prerequisite maintenance that may be required toensure compatibility with anOS or DBMS service pack or security patch.

4. Apply the operating system or database service pack or Security patch to the test/developmentenvironment.

5. Restart the test/development server.6. Ensure that system is still shutdown. If auto start mechanisms are configured to restart Blackboard

after a server restart, remember to shut down the Blackboard system before continuing.7. Apply any necessary Blackboard prerequisite maintenance to the test/development Blackboard

systems.8. Restart the Blackboard systems.9. Check the results either by testing your critical path features or by running your verification

procedures.10. If results are satisfactory, back up the system again. (If not, please log a service request with

Blackboard Technical Support by logging in to Behind the Blackboard athttps://behind.blackboard.com describing the failure.)


9.1 S

P6 BETA D

RAFT



System Planning > Configuration Changes

Configuration ChangesAdministrators who are running Blackboard Learnmay make changes to the system configuration. If contentmanagement is installed, the Administrator must also update the configuration in the Blackboard Learn. This isdone using the push-cs-config-update tool. There are no parameters for this tool.

The following are examples of when this command is used:

l The content management database password is changedl The database server name is changedl The location of Java SE is modifiedl TheWeb Server Hostname is changedl TheWeb Server Port is changedl Database username and password aremodifiedl Blackboard Basedir is changed

How to Make Changes to the System Configuration1. Update the \blackboard\config\bb-config.properties file.2. Update the \blackboard\apps\bbcms\config\bbcms-install.properties file.

This step is only necessary if one of the following properties is updated:

l License Keyl Content management database password

3. Run \blackboard\apps\bbcms\bin\push-cs-config-update.

Hardware Sizing Information for Windows Dell Environments

About Hardware Sizing in a Dell EnvironmentA paradigm shift is underway in online learning. Online learning tools that were once used primarily to augmentclassroom learning havematured to support an onlinemodel in which the CourseManagement System servesas the primary medium for teaching and learning. As the prevalence of high-speed Internet connections andhome computer ownership has grown, so too has the demand for distance learning. Today's learners are turningto web-based distance learning programs as ameans to balance other obligations with the desire to further theireducation, or because they are too far away from the institutions that can best serve their needs.

Themovement toward fully online learningmodels creates new demands for the IT environment and opens upnew opportunities for institutions to use technology as a competitive tool. Demand for higher performance andfaster response times are being driven by two key factors: greater numbers of users, and increased activity byusers. Not only are institutions growing and supporting greater numbers of online users, but users are alsointeracting with the system in new ways that generate substantially greater system load. Users tend to stayonline for much longer periods of time and have greater interactivity with their online courses. The technologymust therefore support large numbers of users who concurrently access the system and require rapid responsetimes so that they can interact without noticeable delays.

When users have consistent and responsive page load times, online learning is easier andmore effective, newforms of teaching and learning can also evolve when interaction has the feeling of being real-time. Traditional


9.1 S

P6 BETA D

RAFT

System Planning > Hardware Sizing Information for Windows Dell Environments

online lectures and online documents can be blended with interactivemedia, allowing students to shareexperiences with each other across geographical boundaries.

This can increase the effectiveness of the learning environment and expand the available market the institutionserves. Institutions want their online learning technology infrastructure to support these new forms of teachingand learning on a scale that allows many more students than could traditionally participate in a classroomapproach.

The online learning architecturemust therefore be highly scalable as well as cost-effective tomaintain so thatinstitutions can focus on teaching instead of technology. The right technology infrastructure for online learningcan create a competitive advantage for the institution.

About Blackboard LearnBlackboard Learn includes Blackboard’s coursemanagement system, course delivery, as well as other coreapplications. Additional capabilities that can be licensed include community engagement, contentmanagement, and outcomes assessment.

About this InformationThe information in this section helps Blackboard clients achieve high service levels and reduce risk by properlyconfiguring and sizing the implementation of Blackboard Learn™ software on Dell™ application and databaseservers. The information is based on a paper written jointly by the Blackboard Performance Team andDell:"From Vision to Reality—Online Learning in a Completely Digital World."

For information about Blackboard’s sizingmethodology, see SizingMethodology for Dell or SizingMethodologyfor Sun.

This information is intended to provide guidance. It is not intended as a service level agreement. Deploymentswill differ from institution to institution based on a variety of factors including the usage of the application. Tolearnmore about systems architecture design and detailed sizing questions, contact your Blackboard AccountManager.

Sizing Methodology for DellSizing is a three-step process consisting of twomodeling exercises and performance testing. Themodelingexercises are used to gather statistical evidence about how users interact with the system. The data generatedfrom these exercises is subsequently used in a series of performance tests. Performance tests help quantifywhat the system will look like under hypothesized workloads and scenarios.

The process begins with understanding how Blackboard clients have used the product in the past. This form ofsampling is called behavior modeling. The objective of this form of sampling is to gather meaningful datarepresenting the following:

l Who is using the system?l What is being done?l Where are they performing their operations?l When are they performing their operations?l How long are users spending performing their operations?

Predictivemodeling is used for new performance testing new features. Little information can be collected abouta feature that has not been built. Because of this, Blackboard hypothesizes user interactions with these newfeatures.

The data collected from bothmodeling exercises is then used for performance testing and benchmarking.Performance benchmarking is conducted by Blackboard with a selected partner of choice (such as Sun


9.1 S

P6 BETA D

RAFT

http://www.dell.com/downloads/global/solutions/public/Brochures/Dell_Bb_wp_Jan7.pdf












Microsystems, Dell, Microsoft, or Oracle) at the Blackboard Performance Laboratory using a combination ofpurchased and donated equipment from a partner. Performance testing and benchmark activities focusprimarily on the performance (response times exhibited by users) and scalability of the system (utilization ofsystem resources such as CPU, memory, and I/O). HP/Mercury LoadRunner is the simulation tool of choicefor generating workload.

Recommended Configurations for DellBlackboard’s recommended configuration is based on a scalable reference architecture that takes advantage oftoday’s latest technologies to support a rich online learning or distance learningmodel. In addition, thisarchitecture offers superior performance and scalability as well as predictable service levels. This informationis based on joint performance testing and benchmarking between Blackboard and Dell to achievemaximumperformance throughput for each configuration.

Deploying Blackboard Learn for DellThe Dell server platform architecture supports Linux andWindows deployments on Intel and AMD processorlines. Performance testing and sizing for Blackboard Learn Release 9.1 focused on Intel’s Nehalem processorseries (5500-series). Both Rack mount and highly dense blade servers are available.

Blackboard Learn has been benchmarked on a variety of Dell systems. Evaluations aremade against both rackmount and highly dense blade servers. These configurations have been evaluated in a non-virtualizedconfiguration, often referred to as “bare-metal.” Additionally, benchmarking has been conducted with up to threevirtualization hypervisors:

l VMware® ESX Server 4 (Linux® andWindows®)l Citrix XenServer 5.5


9.1 S

P6 BETA D

RAFT


l RedHat® Enterprise Linux® 4 & 5 Xen™

Most often these systems contain 2-4 sockets, each with 2, 4, and 6 cores per socket and 8GB to 96GB ofmemory. Throughput performance increases depending on which CPU model is chosen. At the time of thispublishing, the Quad Core Intel® Xeon® 5520 2.26GHz processor with the Hyper-Threading option turned onoffers the best overall price performance. TheQuad Core Intel® Xeon® 55700, 8MB Cache, 2.93GHzprocessor offers the best throughput performance.

Blackboard recommends leveraging both physical and virtual configurations. For years, the Blackboardproducts have been deployed in distributedmanner across multiple physical servers. This configurationremains as the primary option for availability and scalability. In recent releases, many Blackboard customershave introduced virtualized configurations within a physical server using technology such as VMWare, CitrixXenServer, and Red Hat Xen. The combination of both physical and virtualized configurations has introducedresiliency, scalability, and high performance. In Blackboard Learn Release 9.1, Blackboard introduced a 100%64-bit offering for all certified and supported operating systems (OSs) as an additional deployment approach tointegrate with physical and virtual configurations.

Virtualizing at the Application Layer for DellSince Release 8, Blackboard’s Performance Engineering team has executedmore than 4,000 hours ofregression testing and benchmarking of Blackboard Learn using virtualization technologies such as VMwareESX, Citrix XenServer, and Red Hat Xen. The Performance Engineering team has written two papers with Dellpromoting deployments in a virtual manner:

l "Optimizing Blackboard Academic Suite on Dell Servers and Storage"l "From Vision to Reality—Online Learning in a Completely Digital World"

Many customers havemade virtualization part of their deployment approach.

Virtualization enables multiple instances of Guest OS to be deployed on each physical server. Serverprocessor, memory, storage, and networking resources are shared across multiple virtual machines, yet eachvirtual machine (VM) andOS instance can have direct control over specific system resources. BlackboardLearn can then be installed and operated on each VM inmuch the sameway as running each instance on aseparate physical server.

Following are the two key reasons exist for implementing virtualization in the application tier:

l Modern CPUs such as the Intel 5500 series processors are so powerful that a single instance of theOS and its application software components typically cannot fully utilize the CPU. It is more cost-effective to add additional memory to a server and divide the server resources intomultiple virtualmachines than it is to buy more servers.

l Virtualization greatly simplifies provisioning andmanagement of the Blackboard Learn environment.

Most of the virtualization packages deployed in Blackboard production environments include software tools toenable administrators to quickly and easily clone an image of a VM, including the OS and all applicationinstances. This cloned VM image can then be quickly provisioned to a new VMwhen, for example, greatercapacity is needed. Cloning also helps to ensure that all instances of the application are deployed in identicalconfigurations, greatly simplifying ongoingmaintenance of the environment.

Sizing the Application Server for Dell

Dell Configuration InformationApplication tier scalability is achieved using a highly flexible, horizontally scaled infrastructure. Multipleinstances of Blackboard Learn can be deployed on a single Dell server using either a virtualization package or


9.1 S

P6 BETA D

RAFT

http://www.dell.com/downloads/global/solutions/public/Brochures/Dell_Bb_Quest_wp_Jan6.pdf





















bare-metal configuration to isolate Blackboard application instances from each other and tomanage allocationof CPU andmemory resources.

Each Dell server in the application tier can runmultiple VMs, each with its own instance of the BlackboardLearn software. To achieve a high volume of concurrent user sessions, the architecture employs load balancingto distribute requests across all of the Blackboard Learn instances deployed on the virtualized servers.

The architecture takes advantage of 64-bit computing by using Java heap sizes that range from 2G to 16GB foreach Blackboard application instance. Some customers on rare occasions have deployed Java VirtualMachines (JVMs) as large as 32GB in size. The Java heap had been limited to 1.7GB in a 32-bit environment,but this limitation is overcome in the 64-bit environment. Because this feature is now available for all platformswith Blackboard Learn Release 9.1, Blackboard strongly recommends that customers adopt 64-bit for theirprimary deployment OSs.

The architecture includes a recommended 8GB of memory for each VM, leaving up to 2GB for the ApacheWebserver, and up to 2GB for the OS andmonitoring tools. This assumes a JVM heap size of 4GB. Obviously, alarger JVM heap size will require additional memory for the VM. The larger memory footprint for BlackboardLearn enables each application instance tomore efficiently service a high volume of user requests. In otherwords, each application instance can scale vertically while the architecture can also be scaled horizontally bydeploying additional VMs.

This “best of both worlds” approach takes advantage of many application threads in the application tier toservice thousands of requests per minute. The recommended servers for the application tier are DellPowerEdge™R710 servers, which were chosen for their small footprint, low cost, and powerful performancewith Intel 5500 series processors. The application tier could also be built using other Dell servers such as DellPowerEdge R610 rack mountable servers or Dell PowerEdgeM610 orM710 blade servers, all of which featurethe latest Intel 5500 series processors.

The highly flexible and scalable application tier can help customers achieve the following:

l Lower costs: Increased utilization of servers enables good performance on a low-cost, consolidatedinfrastructure.

l Increased flexibility: VMs can bemoved easily to other physical servers to redistribute workloads orrecover quickly from a hardware failure.

l Faster Deployment: With fewer physical systems to setup and configure, less time is required fordeployment.

Will Hyper-Threading Make a Difference?Hyper-threading has been a feature-set in the Intel processor architecture for about a decade. In previousprocessor models, hyper-threading had limited advantages for performance improvements. With the 5500-series processor, the hyper-threading option yielded acceptable performance improvements whenmoving from8CPU threads (2 sockets x 4 cores) to 16 CPU threads (2 sockets x 4 cores x 2 logical hyper-threads). Hyper-threading is a viable, performance configuration worthy of running in a production environment.

Will Tomcat Clustering Make a Difference?Customers should beginmigrating from Tomcat clusters. Tomcat clustering was introduced for scalabilitypurposes when the Blackboard Learn architecture was 32-bit and customers wanted the ability to increase theirmemory usage on a single server. With the option to virtualize on both 32-bit and 64-bit, Blackboard’sbenchmarking efforts havemoved away from Tomcat cluster deployments. Customers can achieve similarperformance in a virtual environment on the same physical server with multiple virtual instances as with a baremetal configuration with many Tomcat cluster instances. The difference in configurations is a smaller demandon the Apache or IIS web server fronting the Tomcat instance(s). The option to deploy a 64-bit JVM with largerheap sizes has suppressed the need for customers to run in a cluster option.


9.1 S

P6 BETA D

RAFT


Blackboard recommends that customers consider a deployment approach consisting of larger 64-bit JVMs thatare distributed across physical servers with the option to virtualize the hardware to take advantage of the CPUandMemory capacity of these systems.

Sizing by CPU and MemoryThe configuration table in this section includes options to size based on 2 CPU threads versus 4 CPU threadsas well as an option to size based on a 32-bit OS versus 64-bit OS. As noted above, Blackboard recommendsdeploying Blackboard Learn in a 64-bit configuration.

Choosing the CPU capacity should be a decision based on two inputs:

l CPU Utilization: A metric based on an average utilization of the CPUs between two points in timel Run Queue: Responsible for queuing CPU operations while waiting for the CPU to process a

request

CPU utilization is a topic argued by many as to what percentage value is optimal for a production system. Thegoal should be to use as much of the CPU available. So, an obvious goal is to identify a workload that will fullyutilize the CPU, but not at the expense of having a high run queue. For every request that is stuck in the runqueue, latency will be added until the CPU can service the request. CPU utilization of 100% is only one factorthat will force a request into a wait state.

A 2 CPU thread deployment is acceptable for a 32-bit deployment and would be theminimum configurationrequirement for a 2GB JVM in a 64-bit address space. Customers seeking larger JVMs in the range of 4GB to16GB should consider a 4 CPU thread deployment approach because of better throughput processing of Javagarbage collection in parallel. Response times will improve with a larger heap andmore available CPU threadsfor processing. Allocations of more than 4 CPUs did not yield major performance improvements and, therefore,are not recommended.

Customers should be aware of their run queue for capacity management. A run queue equal or slightly abovethe CPU count is acceptable at normal times and during peak. When the run queue is double or even greater theCPU count, customers should strongly consider allocatingmore CPUs to the configuration or increasing thenumber of instances of the application. Special care and attention should be applied to the database whenmaking the decision to introduce additional application servers. Impact can be seen on thememory footprint ofthe database, as well as the load average of the system because of the need for more remote connections andprocesses.

Allocations of memory should be based on need and rate of collection. The application is 100% Java-based andthus has a greater demand for memory within the JVM than in previous versions of the application. A 32-bit1.7GB JVM simply will not satisfy the performance demands of the user community as it was capable of doingin past releases with a hybrid technology stack that included PERL. Therefore, customers deploying with a 32-bit configuration will require greater amounts of equipment to support faster responsiveness and largerconcurrency. A 64-bit JVM sized between 4GB and 16GB will provide serviceable response times with lesslatency. Memory tends to be the primary resource constraint. As a result, Blackboard recommends using alarger JVM with the performance options defined in the Release Notes for the release that you are installing.

Bare-Metal or Virtual ConfigurationsThe sizing table in this sectionmakes no assumptions about whether a deployment is virtual or bare-metal. Theterm bare-metal implies a single operating system installed on a single physical server. Clients have the optionto deploy their environments in either a virtual or bare-metal configuration. The CPU andMemory capacity ofthe recommended Dell systems is ideal for virtualized deployments. Customers will be able to savesubstantially year after year by choosing to deploy in a virtualizedmanner.

In the paper "From Vision to Reality—Online Learning in a Completely Digital World," Blackboard deployed upto four installations of Blackboard Learn on a single R710 server. Each VM was configured to provide fourvirtual CPUs to each installation, as well as 8GB of memory to the guest OS. The Blackboard Learn JVM was


9.1 S

P6 BETA D

RAFT















configured for 64-bit addressablememory and a 4GB maximum heap size. The consolidation of four VMs to onephysical server loaded with 48GB of memory instead of purchasing four physical servers with 8GB to 12GB ofmemory can result in amore than 300% cost savings. The cost of memory justifies the overall savings ofpurchasing fewer, under-sized systems.

Preparing for the Westmere EP-Processor and R910 NehalemAt the time this document was published, Dell had yet to release the 5600-series (Westmere EP-Processor) forthe R610, R710, M610 andM710 systems. In addition, the R910 Nehalem, which leverages an 8-coreprocessor (Intel® Xeon® X7560), was not ready for production. Changes will bemade to this information toreflect the new processors andmodels recommended for sizing purposes. The following changes will bemadeafter these new CPUs andmodels become available:

Current Recommendation:Intel® Xeon® 5520 series (2.26Ghz, 8M Cache, Turbo, HT, 1066MHz Max Memory)

Future Recommendation:Intel® Xeon® E5620 series (2.40GHz, 12M cache, Turbo, HT, 1066MHz Max Memory)

Current Recommendation:Intel® Xeon® X5550 (2.66Ghz, 8M Cache, Turbo, HT, 1333MHz Max Memory)

Future Recommendation:Intel® Xeon® X5650 (2.66GHz, 12M cache, Turbo HT, 1333MHz Max Memory) – 6-core

Current Recommendation:Intel® Xeon® X7460 (2.67GHz, 16M Cache, 1066Mhz FSB)

Future Recommendation:Intel® Xeon® X7560 (2.26GHz), 24M Cache, 1066Mhz FSB) – 8-core

Sizing the Database for DellThe Dell M610, R610, and R710 are ideal for runningMicrosoft SQL Server 2005 or 2008 andOracle in standardand advanced sizing configurations. Blackboard recommends using the dual-socket, quad core configuration.These systems also offer a Hyper-Threading option, which have revealed in benchmarks to provide aperformance advantage.

Memory requirements will vary depending on deployment within a 32-bit or 64-bit configuration. All certified andsupported configurations are available in both 32-bit and 64-bit address spaces. Each of these systems can beused for availability purposes in anOracle RAC configuration or Microsoft SQL Server Active/Passive FailoverCluster. Blackboard offers support for RAC with all versions of Oracle supported by Blackboard. For information about running Blackboard Learn with RAC, seeOracle RAC Support on UNIX. To learnmore aboutthe SQL Server Failover capabilities of Blackboard Learn, contact Blackboard Consulting.

For complex sizing configurations, Dell PowerEdge R710 and R900 servers are used to provide increasedcapacity. A high availability option is supported through an optional cluster configuration with a redundantinstance of the database running on a second server using Oracle RAC or SQL Server Failover capabilities toprovide the redundant database functionality.

Sizing for memory is absolutely critical for ensuring a high-performing and reliable configuration. Oracleconfigurations require a set of inputs to calculate the SGA and PGA spaces of memory. The SGA will containboth the SQL area for caching statements as well as the buffer cache for storing blocks of data in memory. ThePGA space will maintain the process memory requirements as well as hash and sorting space for queryexecution. The combination of these two regions makes up the requirements of Oracle memory.

SQL Server will have similar memory requirements as Oracle. SQL Server memory is broken down into threeregions:


9.1 S

P6 BETA D

RAFT


l Buffer Pooll Procedure Cachel MemToLeave

These regions are transparent to DBAs to simplify applicationmanagement purposes.

Sizing Storage for Dell

Media and Content StorageBlackboard Learn uses a non-relational file system for the storage of multi-media and binary files such as textfiles, images, word processing documents, spreadsheets, and other file types used in teaching and learning.

Blackboard recommends that clients on UNIX platforms use a network file share (NFS).

Blackboard recommends that clients onWindows use a common Internet file system (CIFS).

Both of these network-based file system protocols allow for simplifiedmanagement, ease of data expansion,andmultiple access points from applications servers. Load balanced installations can use both file systemtypes. Deploying storage on a local application server can also be implemented, but Blackboard does notrecommend doing so.

File system content can range from 5–100 times the size of the database content. File system content from ablock perspective is touched less frequently than the database file system. Clients can opt to configure theirsystems to a lesser performing RAID configuration with slower spindles because I/O performance is less of aconcern.

Blackboard recommends that clients determine a storage quota per student and faculty member as well asaccount for passive users that require less storage quota. Assume that faculty will have greater storagerequirements. Following is a simple example:

Profile Quota Users Storage Needs

Faculty 5GB 500 2.5 TB + RAID Considerations

Student 500MB 10,000 5TB + RAID Considerations

Other 20MB 1,000 20GB + RAID Considerations

Sizing the file system depends on archival strategies, datamanagement policies, RAID configuration, and I/Operformance standards. Blackboard typically assumes that the file system will require about 100+ I/O persecond per application server at peak. To calculate your I/O per second needs, multiply this metric against thenumber of application servers in your deployment.

Database Data File StorageBlackboard Learn uses a relational database system (Oracle and SQL Server) for the storage of databasecontent.

Clients on UNIX platforms may use one of the following:

l A network file share (NFS)l ISCSI (networked block-level)l Direct attached storage (block-level)

Clients onWindows SQL Server may use one of the following:

l ISCSI (networked block-level)l Direct attached storage (block-level)


9.1 S

P6 BETA D

RAFT


The database storage requirements of institutions can vary. Typically, database content can range from 5–100times less than file system content. Sizing the database depends on archival strategies, datamanagementpolicies, RAID configuration, and, most importantly, I/O performance standards. Blackboard typically assumesthat the file system will require between 350 to 600 I/O per second per application server at peak. To calculateyour I/O per second needs, multiply this metric against the number of application servers in your deployment.The primary driver for database storage should be performance.

Storage PerformanceThe database tier has variable I/O performance needs, therefore, Blackboard recommends using fibre channeldrives with 10,000 to 15,000 RPM capacity. To deliver adequate I/O throughput, Blackboard also recommendsusing smaller capacity drives so that there will bemore spindles to reduce seek times and improve data transferrates.

The I/O performance requirements are not the same for the shared file system. Slower, condensed storageoptions using SATA or SAS disks in the range of 7,200 or 10,000 RPM aremore than adequate. Theconfigurations defined in this topic have been validated to support adequate I/O throughput for the user loadsdefined for each configuration. When sizing storage, be sure to do the following:

1. Determine how much storage your institution will need.2. Determine how this storage can be spread across multiple trays and disks to optimize performance

throughput.

Remember that the shared file system can require upwards of 5–100 times the amount of storage of thedatabase. However, the database can use 5–20 times the number of I/O operations per second than the sharedfile system.

DescriptionStandard Advanced Complex

ContentStorageTier

UNIX: Network AttachedStorage Architecture

Windows: CIFS Architecture

Up to 2.2 TB of usable storage

7.2k to 10k RPM SATA or SASdisks

UNIX: Network AttachedStorage Architecture


Up to 5 TB of usable storage


UNIX: Network Attached StorageArchitecture




DatabaseStorageTier

UNIX: Network AttachedStorage Architecture, ISCSI, orFC-SAN

Windows: ISCSI or FC-SAN

Up to 500 GB of usable storage

10k to 15k RPM FC




10k to 15k RPM FC

UNIX: Network Attached StorageArchitecture, ISCSI, or FC-SAN



10k to 15k RPM FC


9.1 S

P6 BETA D

RAFT


Blackboard Learn Release 9.1 Configurations for DellSizingCategory Standard Advanced Complex

Description The Standard sizingconfiguration is designed foravailability and performance.Options exist for both physicaldistributions of applicationservers and/or virtualizedinstances of the application.The institution has minimaldeployment of distancelearning or connectedclassroom initiatives (less than5%).

The Advanced sizingconfiguration is designed forhigh-availability and high-performance. The model isdesigned for heavy adoption ofthe product across institutionsof varying sizes. Customersdeploying distance learningprograms or with connectedclassroom initiatives to aportion of the community fallinto this category.

The Complex sizingconfiguration is designed formassive adoption, high-availability, and high-performance. Customersdeploying predominatelydistance learning programs orwith connected classroominitiatives fall into this category.Customers with largercommunity sizes (greater than250,000 users) fall into thiscategory.

Application Server Configuration

Number of OSInstances(Physical orVirtual)

2 to 4 4 to 8 8 to 16

Minimum CPUConfigurationPer OSInstance

2 CPU ThreadsIntel® Xeon® 5520 series(2.26Ghz, 8M Cache, Turbo,HT, 1066MHz Max Memory)



2 CPUVirtualizationCollapse Ratio(VMs toPhysicalServer)

4:1 with Hyper-Threading OFF 4:1 with Hyper-Threading OFF 4:1 with Hyper-Threading OFF

Ideal CPUConfigurationPer OSInstance

4 CPU ThreadsIntel® Xeon® X5550 (2.66Ghz,8M Cache, Turbo, HT,1333MHz Max Memory)



4 CPUVirtualizationCollapse Ratio(VMs toPhysicalServer

2:1 with Hyper-Threading OFF-or-4:1 with Hyper-Threading ON



32-bit MemoryRequirementsPer OSInstance

4GB to 8GB 4GB to 8GB 4GB to 8GB


8GB to 16GB recommended 8GB to 16GB recommended 8GB to 16GB recommended

I/O Workload atPeak Hour

300 to 500 I/Os 500 to 1000 I/Os 1000 to 2000 I/Os


9.1 S

P6 BETA D

RAFT


Hits/Hour atPeak Hour

Up to 4 Million Hits/Hour Up to 8 Million Hits/Hour Up to 12 Million Hits/Hour

Characteristics With 4 CPU threads perinstance and a 64-bitdeployment across 4instances, this configurationwill support as many as 20,000concurrent sessions for a peakhour. A concurrent session is auser who has logged into theapplication within the last hour.With 2 CPU threads perinstance and a 32-bitdeployment across 4instances, this configurationwill support approximately2,000 concurrent sessions.

Results will vary depending onthe use of memory intensiveareas of the application, suchas Assessment and GradeCenter.Memory has thegreatest impact on the sessionconcurrency andresponsiveness of theapplication, followed by CPUcapacity. Consider a largermemory footprint for evensmaller workloads to deliverfaster page responsiveness.

With 4 CPU threads perinstance and a 64-bitdeployment across 4instances, this configurationwill support as many as 40,000concurrent sessions for a peakhour. A concurrent session is auser who has logged into theapplication within the last hour.With 2 CPU threads perinstance and a 32-bitdeployment across 4instances, this configurationwill support approximately4,000 concurrent sessions.

Results will vary depending onthe use of memory intensiveareas of the application, suchas Assessment and GradeCenter.Memory has thegreatest impact on the sessionconcurrency andresponsiveness of theapplication, followed by CPUcapacity. Consider a largermemory footprint for evensmaller workloads to deliverfaster page responsiveness.

With 4 CPU threads perinstance and a 64-bitdeployment across 4instances, this configurationwill support as many as 80,000concurrent sessions for a peakhour. A concurrent session is auser who has logged into theapplication within the last hour.With 2 CPU threads perinstance and a 32-bitdeployment across 4instances, this configurationwill support approximately8,000 concurrent sessions.

Results will vary depending onthe use of memory intensiveareas of the application suchas Assessment and GradeCenter.Memory has thegreatest impact on the sessionconcurrency andresponsiveness of theapplication, followed by CPUcapacity. Consider a largermemory footprint for evensmaller workloads to deliverfaster page responsiveness.

Database Server Configuration

Minimum CPUConfiguration

4 to 8 CPU ThreadsIntel® Xeon® 5520 series(2.26Ghz, 8M Cache, Turbo,HT, 1066MHz Max Memory)



Ideal CPUConfiguration


16 CPU ThreadsIntel® Xeon® X5570 (2.93Ghz, 8M Cache, Turbo, HT,1333MHz Max Memory)

24+ CPU ThreadsIntel® Xeon® X7460 (2.67GHz,16M Cache, 1066Mhz FSB)

MemoryRequirements



600 to 1,200 I/Os 1,500 to 3,000 I/Os 4,500 to 10,000 I/Os

AvailabilityApproach

Failover clustering approachesthat leverage Active/Passivedatabase configurationsshould be considered for thisdeployment.

Failover clustering approachesthat leverage Active/Passivedatabase configurationsshould be considered for thisdeployment. Linuxdeployments may considerOracle® Real ApplicationClusters (Oracle RAC).

Failover clustering approachesthat leverage Active/Passivedatabase configurationsshould be considered for thisdeployment. Linuxdeployments should considerOracle® Real ApplicationClusters (Oracle RAC).

Oracle Memory Requirements


9.1 S

P6 BETA D

RAFT

System Planning > Hardware Sizing Information for UNIX Sun Environments

Estimated SGASize


Processes 600 to 1,200 2,000 to 4,000 5,000 to 10,000

EstimatedProcess Size

3M to 7M 3M to 7M 3M to 7M

Estimated PGAMemory


Hardware Sizing Information for UNIX Sun Environments

About Hardware Sizing in a Sun Microsystems EnvironmentA paradigm shift is underway in online learning. Online learning tools that were once used primarily to augmentclassroom learning havematured to support an onlinemodel in which the CourseManagement System servesas the primary medium for teaching and learning. As the prevalence of high-speed Internet connections andhome computer ownership has grown, so too has the demand for distance learning. Today's learners are turningto web-based distance learning programs as ameans to balance other obligations with the desire to further theireducation, or because they are too far away from the institutions that can best serve their needs.

Themovement toward fully online learningmodels creates new demands for the IT environment and opens upnew opportunities for institutions to use technology as a competitive tool. Demand for higher performance andfaster response times are being driven by two key factors: greater numbers of users, and increased activity byusers. Not only are institutions growing and supporting greater numbers of online users, but users are alsointeracting with the system in new ways that generate substantially greater system load. Users tend to stayonline for much longer periods of time and have greater interactivity with their online courses. The technologymust therefore support large numbers of users who concurrently access the system and require rapid responsetimes so that they can interact without noticeable delays.

When users have consistent and responsive page load times, online learning is easier andmore effective, newforms of teaching and learning can also evolve when interaction has the feeling of being real-time. Traditionalonline lectures and online documents can be blended with interactivemedia, allowing students to shareexperiences with each other across geographical boundaries.

This can increase the effectiveness of the learning environment and expand the available market the institutionserves. Institutions want their online learning technology infrastructure to support these new forms of teachingand learning on a scale that allows many more students than could traditionally participate in a classroomapproach.

The online learning architecturemust therefore be highly scalable as well as cost-effective tomaintain so thatinstitutions can focus on teaching instead of technology. The right technology infrastructure for online learningcan create a competitive advantage for the institution.

About Blackboard LearnBlackboard Learn includes Blackboard’s coursemanagement system, course delivery, as well as other coreapplications. Additional capabilities that can be licensed include community engagement, contentmanagement, and outcomes assessment.

About this InformationThe information in this section helps Blackboard clients achieve high service levels and reduce risk by properlyconfiguring and sizing the implementation of Blackboard Learn™ software on Sun™ application and database


9.1 S

P6 BETA D

RAFT


servers. The information is based on analysis and benchmarkingmodels from the Blackboard PerformanceTeam in conjunction with Sun.

For information about Blackboard’s sizingmethodology, see SizingMethodology for Sun.

This information is intended to provide guidance. It is not intended as a service level agreement. Deploymentswill differ from institution to institution based on a variety of factors including the usage of the application. Tolearnmore about systems architecture design and detailed sizing questions, contact your Blackboard AccountManager.

Sizing Methodology for SunSizing is a three-step process consisting of twomodeling exercises and performance testing. Themodelingexercises are used to gather statistical evidence about how users interact with the system. The data generatedfrom these exercises is subsequently used in a series of performance tests. Performance tests help quantifywhat the system will look like under hypothesized workloads and scenarios.

The process begins with understanding how Blackboard clients have used the product in the past. This form ofsampling is called behavior modeling. The objective of this form of sampling is to gather meaningful datarepresenting the following:

l Who is using the system?l What is being done?l Where are they performing their operations?l When are they performing their operations?l How long are users spending performing their operations?

Predictivemodeling is used for new performance testing new features. Little information can be collected abouta feature that has not been built. Because of this, Blackboard hypothesizes user interactions with these newfeatures.

The data collected from bothmodeling exercises is then used for performance testing and benchmarking.Performance benchmarking is conducted by Blackboard with a selected partner of choice (such as SunMicrosystems, Dell, Microsoft, or Oracle) at the Blackboard Performance Laboratory using a combination ofpurchased and donated equipment from a partner. Performance testing and benchmark activities focusprimarily on the performance (response times exhibited by users) and scalability of the system (utilization ofsystem resources such as CPU, memory, and I/O). HP/Mercury LoadRunner is the simulation tool of choicefor generating workload.

Recommended Configurations for SunBlackboard’s recommended configuration is based on a scalable reference architecture that takes advantage oftoday’s latest technologies to support a rich online learning or distance learningmodel. In addition, thisarchitecture offers superior performance and scalability as well as predictable service levels. This informationis based on joint performance testing and benchmarking between Blackboard and Sun to achievemaximumperformance throughput for each configuration.


9.1 S

P6 BETA D

RAFT


Deploying Blackboard Learn for SunCustomers who deploy Blackboard Learn on Sun hardware have the flexibility to choose from a variety ofserver architectures that support Solaris, Linux, andWindows. Sun offers hardwaremodels built onUltraSPARC T2/T1, AMD Opteron, and Intel Xeon processor platforms.

The UltraSPARC architecture is well suited for Blackboard Learn. Clients can deploy either the Sun Fire™T5120/T5220 server for price and throughput performance, or the Sun Fire™T5140/T5240 for overall throughputperformance. All 6 units have the capacity to scale to 6 cores or 8 cores with aminimum of 16GB of memory.The Sun Fire™T5140/T5240 has the capacity of 2 sockets per physical machine.

Blackboard recommends leveraging both physical and virtual configurations. For years, the Blackboardproducts have been deployed in distributedmanner across multiple physical servers. This configurationremains as the primary option for availability and scalability. In recent releases, many Blackboard customershave introduced virtualized configurations within a physical server using technology such as Solaris Zones.The combination of both physical and virtualized configurations has introduced resiliency, scalability, and highperformance. In Blackboard Learn Release 9.1, Blackboard introduced a 100% 64-bit offering for all certifiedand supported operating systems (OSs) as an additional deployment approach to integrate with physical andvirtual configurations.

Sizing the Application Server for Sun

Sun Configuration InformationApplication tier scalability is achieved using a highly flexible, horizontally scaled infrastructure. Multipleinstances of Blackboard Learn can be deployed on a single Sun server using either a virtualization package orbare-metal configuration to isolate Blackboard application instances from each other and tomanage allocationof CPU andmemory resources.


9.1 S

P6 BETA D

RAFT


Each Sun server in the application tier can runmultiple zones each with its own instance of the BlackboardLearn software. To achieve a high volume of concurrent user sessions, the architecture employs load balancingto distribute requests across all of the Blackboard Learn application instances deployed on the zones.

The architecture takes advantage of 64-bit computing by using Java heap sizes that range from 2G to 16GB foreach Blackboard application instance. Some customers on rare occasions have deployed Java VirtualMachines (JVMs) as large as 32GB in size. The Java heap had been limited to 1.7GB in a 32-bit environment,but this limitation is overcome in the 64-bit environment. Because this feature is now available for all platformswith Blackboard Learn Release 9.1, Blackboard strongly recommends that customers adopt 64-bit for theirprimary deployment OSs.

The architecture includes a recommended 8GB of memory for each VM, leaving up to 2GB for the ApacheWebserver, and up to 2GB for the OS andmonitoring tools. This assumes a JVM heap size of 4GB. Obviously, alarger JVM heap size will require additional memory for the VM. The larger memory footprint for BlackboardLearn enables each application instance tomore efficiently service a high volume of user requests. In otherwords, each application instance can scale vertically while the architecture can also be scaled horizontally bydeploying additional VMs.

This “best of both worlds” approach takes advantage of many application threads in the application tier toservice thousands of requests per minute. The recommended servers for the application tier are Sun SPARCEnterprise T5120 and T5140models, which were chosen for their small footprint, moderate cost, and powerfulthroughput performance.

The highly flexible and scalable application tier can help customers achieve:

l Lower costs: Increased utilization of servers enables good performance on a low-cost consolidatedinfrastructure.

l Increased flexibility: VMs can bemoved easily to other physical servers to redistribute workloads orrecover quickly from a hardware failure.

l Faster Deployment: With fewer physical systems to setup and configure, less time is required fordeployment.

Will Tomcat Clustering Make a Difference?Customers should beginmigrating from Tomcat clusters. Tomcat clustering was introduced for scalabilitypurposes when the Blackboard Learn architecture was 32-bit and customers wanted the ability to increase theirmemory usage on a single server. With the option to virtualize on both 32-bit and 64-bit, Blackboard’sbenchmarking efforts havemoved away from Tomcat cluster deployments. Customers can achieve similarperformance in a virtual environment on the same physical server with multiple virtual instances as with a baremetal configuration with many Tomcat cluster instances. The difference in configurations is a smaller demandon the Apache or IIS web server fronting the Tomcat instance(s). The option to deploy a 64-bit JVM with largerheap sizes has suppressed the need for customers to run in a cluster option.


Sizing the Database for SunThe Sun Fire™T5220 and T5240 are ideal for running Oracle in small andmedium size institutions. Bothsystems have 6-core and 8-core configurations available. Memory requirements will vary depending ondeployment within a 32-bit or 64-bit configuration. Each of these systems can be used for availability purposesin anOracle® Real Application Clusters (Oracle RAC) configuration. Blackboard offers support for RAC with allversions of Oracle supported by Blackboard. For information about running Blackboard Learn with RAC, seeOracle RAC Support on UNIX.


9.1 S

P6 BETA D

RAFT


For large campus configurations, a Sun Fire™T5440 or Sun SPARC® EnterpriseM5000 server is used insteadof the Sun Fire T5220 or T5240 server to provide increased capacity. A high availability option is supportedthrough an optional cluster configuration with a redundant instance of the database running on a second serverusing Oracle RAC to provide the redundant database functionality.

Sizing for memory is absolutely critical for ensuring a high-performing and reliable configuration. Oracleconfigurations require a set of inputs to calculate the SGA and PGA spaces of memory. The SGA will containboth the SQL area for caching statements, as well as the buffer cache for storing blocks of data in memory. ThePGA space will maintain the process memory requirements, as well as hash and sorting space for queryexecution. The combination of these two regions makes up the requirements of Oracle memory.

Sizing Storage for Sun

Media and Content StorageBlackboard Learn uses a non-relational file system for the storage of multi-media and binary files such as textfiles, images, word processing documents, spreadsheets, and other file types used in teaching and learning.

Blackboard recommends that clients on UNIX platforms use a network file share (NFS).

Blackboard recommends that clients onWindows use a common Internet file system (CIFS).

Both of these network-based file system protocols allow for simplifiedmanagement, ease of data expansion,andmultiple access points from applications servers. Load balanced installations can use both file systemtypes. Deploying storage on a local application server can also be implemented, but Blackboard does notrecommend doing so.

File system content can range from 5–100 times the size of database content. File system content from a blockperspective is touched less frequently than the database file system. Clients can opt to configure their systemsto a lesser performing RAID configuration with slower spindles because I/O performance is less of a concern.

Blackboard recommends that clients determine a storage quota per student and faculty member as well asaccount for passive users that require less storage quota. Assume that faculty will have greater storagerequirements. Following is a simple example:

Profile Quota Users Storage Needs

Faculty 5GB 500 2.5 TB + RAID Considerations

Student 500MB 10,000 5TB + RAID Considerations

Other 20MB 1,000 20GB + RAID Considerations

Sizing the file system depends on archival strategies, datamanagement policies, RAID configuration, and I/Operformance standards. Blackboard typically assumes that the file system will require about 100+ I/O persecond per application server at peak. To calculate your I/O per second needs, multiply this metric against thenumber of application servers in your deployment.

Database Data File StorageBlackboard Learn uses a relational database system (Oracle and SQL Server) for the storage of databasecontent.

Clients on UNIX platforms may use one of the following:

l A network file share (NFS)l ISCSI (networked block-level)l Direct attached storage (block-level)

Clients onWindows SQL Server may use one of the following:


9.1 S

P6 BETA D

RAFT


l ISCSI (networked block-level)l Direct attached storage (block-level)

The database storage requirements of institutions can vary. Typically, database content can range from 5–100times less than file system content. Sizing the database depends on archival strategies, datamanagementpolicies, RAID configuration, and, most importantly, I/O performance standards. Blackboard typically assumesthat the file system will require between 350 to 600 I/O per second per application server at peak. To calculateyour I/O per second needs, multiply this metric against the number of application servers in your deployment.The primary driver for database storage should be performance.

Storage PerformanceThe database tier has variable I/O performance needs, therefore, Blackboard recommends using fibre channeldrives with 10,000 to 15,000 RPM capacity. To deliver adequate I/O throughput, Blackboard also recommendsusing smaller capacity drives so that there will bemore spindles to reduce seek times and improve data transferrates.

The I/O performance requirements are not the same for the shared file system. Slower, condensed storageoptions using SATA or SAS disks in the range of 7,200 or 10,000 RPM aremore than adequate. Theconfigurations defined in this topic have been validated to support adequate I/O throughput for the user loadsdefined for each configuration. When sizing storage, be sure to do the following:

1. Determine how much storage your institution will need.2. Determine how this storage can be spread across multiple trays and disks to optimize performance

throughput.

Remember that the shared file system can require upwards of 5–100 times the amount of storage of thedatabase. However, the database can use 5–20 times the number of I/O operations per second than the sharedfile system.

Description Standard Advanced Complex

ContentStorageTier

UNIX: Network AttachedStorage Architecture or ZFS forSolaris only


Up to 2.2 TB of usable storage


UNIX: Network AttachedStorage Architecture or ZFS forSolaris only




UNIX: Network Attached StorageArchitecture or ZFS for Solarisonly




DatabaseStorageTier



Up to 500 GB of usable storage

10k to 15k RPM FC




10k to 15k RPM FC

UNIX: Network Attached StorageArchitecture, ISCSI, or FC-SAN



10k to 15k RPM FC


9.1 S

P6 BETA D

RAFT


Blackboard Learn Release 9.1 Configurations for SunSizingCategory Standard Advanced Complex

Description The Standard sizingconfiguration is designed foravailability and performance.Options exist for both physicaldistributions of applicationservers and/or virtualizedinstances of the application.The institution has minimaldeployment of distancelearning or connectedclassroom initiatives (less than5%).

The Advanced sizingconfiguration is designed forhigh-availability and high-performance. The model isdesigned for heavy adoption ofthe product across institutionsof varying sizes. Customersdeploying distance learningprograms or have connectedclassroom initiatives to aportion of the community fallinto this category.

The Complex sizingconfiguration is designed formassive adoption, high-availability and high-performance. Customersdeploying predominatelydistance learning programs orhave connected classroominitiatives fall into this category.Customers with largercommunity sizes (greater than250,000 users) fall into thiscategory.

Application Server Configuration

Number of OSInstances(Physical orVirtual)

2 to 4 4 to 8 8 to 16

Minimum CPUConfigurationPer OSInstance

1 x 8-Core 1.2 GHzUltraSPARC T2 64 Threads


2 x 8-Core 1.4 GHzUltraSPARC T2 Plus 128Threads

Minimum CPUCollapse Ratio(Zone toPhysicalServer)

4:1 (Zone Configuration) 4:1 ( Zone Configuration ) 6:1 ( Zone Configuration )

Ideal CPUConfigurationPer OS Instance




Ideal CPUVirtualizationCollapse Ratio(Zone toPhysicalServer)

4:1 (Zone Configuration) 6:1 ( Zone Configuration ) 6:1 ( Zone Configuration )


8GB to 16GB recommended 8GB to 16GB recommended 8GB to 16GB recommended


300 to 500 I/Os 500 to 1000 I/Os 1000 to 2000 I/Os

Hits/Hour atPeak Hour

Up to 4 Million Hits/Hour Up to 8 Million Hits/Hour Up to 12 Million Hits/Hour


9.1 S

P6 BETA D

RAFT


SizingCategory Standard Advanced Complex

Characteristics With 8 CPU threads perinstance and a 64-bitdeployment across 4instances, this configurationwill support as many as 20,000concurrent sessions for a peakhour. A concurrent session is auser who has logged into theapplication within the last hour.


With 16 to 20 CPU threads perinstance and a 64-bitdeployment across 6instances, this configurationwill support as many as 40,000concurrent sessions for a peakhour. A concurrent session is auser who has logged into theapplication within the last hour.


With 16 to 20 CPU threads perinstance and a 64-bitdeployment across 6instances, this configurationwill support as many as 80,000concurrent sessions for a peakhour. A concurrent session is auser who has logged into theapplication within the last hour.


Database Server Configuration

Minimum CPUConfiguration




Ideal CPUConfiguration


8 x 2.53 GHz SPARC64 VII on4 Boards


MemoryRequirements



600 to 1,200 I/Os 1,500 to 3,000 I/Os 4,500 to 10,000 I/Os

AvailabilityApproach

Failover clustering approachesthat leverage Active/Passivedatabase configurationsshould be considered for thisdeployment.

Failover clustering approachesthat leverage Active/Passivedatabase configurationsshould be considered for thisdeployment. Solarisdeployments may considerOracle® Real ApplicationClusters (Oracle RAC)

Failover clustering approachesthat leverage Active/Passivedatabase configurationsshould be considered for thisdeployment. Solarisdeployments should considerOracle® Real ApplicationClusters (Oracle RAC)

Oracle Memory Requirements

Estimated SGASize


Processes 600 to 1,200 2,000 to 4,000 5,000 to 10,000

EstimatedProcess Size

3M to 7M 3M to 7M 3M to 7M

Estimated PGAMemory



9.1 S

P6 BETA D

RAFT

System Planning > Architecture

Architecture

About the File SystemBlackboard Learn by default installs into a home directory named blackboard. It is represented in allexamples and paths as blackboard_home. This directory not only holds all of the application files, but it isalso the location where content items and log files are stored.

Administrators should not have any reason to delete or modify any of the application files. Doing somay causethe system to fail. This topic reviews several of themore important areas of the file system.

Command Line ToolsMost of the command line utilities are stored in blackboard_home/tools/admin directory. The tools forbatch archive/restore/export/import and batch copy are found in the blackboard_home/apps/content-exchange/bin.

HTTP CompressionEnable GZip compression through the bb-config.properties file by toggling it on or off. Both IIS andApache support GZip as a native compression ability.

Content StorageContent is stored in the blackboard_home/content/vi directory. Each directory contains the followingfolders:

l admin: This directory stores images associated with System Reporting.l branding: This directory stores the HTML that determines how theGateway page is displayed.l Courses: This directory includes storage areas for each Course andOrganization. Content items

uploaded to the Course or Organization are stored here.l images: This directory stores images used on the system.l modules: This directory stores JSP pages for portal modules.l plugins: This directory stores System Extensions.l recyclebin: This directory includes deleted Course content. Content must be removed from this

directory or it will be stored indefinitely.l sessions: This directory stores session-specific data for users.l sponsors: This directory stores sponsorship information and images.

QueriesPaged searching is used in admin panel user and course searches, course search/catalog, and the userdirectory. Only one page of necessary data records are loaded at a time by using highly tuned SQL queries. Theconsumption of memory is relatively low with this type of query, and results in a short Garbage Collection timeto reclaim the usedmemory.

Hierarchical data uses the native database syntax CONNECT BY statements in Oracle, and recursive CommonTable Expressions in SQL Server when performing a hierarchical query.


9.1 S

P6 BETA D

RAFT


LogsAll logs are stored in the blackboard_home\logs directory. Logs can bemanaged and viewed from theLogs link on the System Control Panel in the user interface. Notable logs are bb-session-log.txt whichrecords suspicious session fingerprint activity, and bb-sms-log.txt which records automatic syncattempts.

The verbosity of some logs can be adjusted to providemore or less information. Run PushConfigUpdates toactivate the changes. To learnmore, see PushConfigUpdates.

The verbosity of theblackboard_home/logs/bb-services-log.txt log is controlled by theblackboard.service.log.param.logdef.default.verbosity property in the service-config.properties file. The default value, fatal, logs only fatal events. The valid options from lessverbosity to more verbosity are: "fatal," "error," "warning," "information," "debug". Run PushConfigUpdatesto activate the changes. To learnmore, see PushConfigUpdates.

Setting Up the Content CollectionThe Content Collection is “disabled” after installation. This gives the Administrator a chance to configure theContent Collection beforemaking it publicly available. Turn on the Content Collection and appropriate Toolsand Features. If Portfolios are enabled, select which roles may use this feature.

Turn on the Content Collection and its features from:

Administrator Panel > Content Management > Feature and Tool Management > Feature and ToolAvailability

Enabling SSLAuthentication forWeb Folders (also known as WebDAV) occurs in plain text. Blackboard stronglyrecommends running SSL. If SSL is not used, authenticationmay be compromised.

How to Set up the PortalThis section is relevant only if your school licenses community engagement. Follow the steps below to set upthe Portal:

1. If Portal Direct Entry is enabled, disable the Content Collection for Guests and any other rolesthat should not use it, such as Prospective Students andObservers.

Administrator Panel > Communities > Tabs and Modules > Tab Groups > Tab Group:Content Collection > Edit

2. Select Edit from the contextual menu next to each Content Collectionmodule then set theSystemAvailability of themodule.

3. Enable Content Management Portal Modules. These include: Bookmarks, Course Content,Institution Content, My Content, My Portfolios, Organization Content, Search, andWorkflowActivities.

Administrator Panel > Communities > Tabs and Modules > Modules4. Select Edit Properties next to each Content Management Module to edit availability.

How to Configure Content Management SettingsThe following steps explain which Settings must be configured initially:


9.1 S

P6 BETA D

RAFT


1. Set up Virtual Hard Drives for users. This determines which roles have folders available in theusers directory. The quota for these folders is set in Default Folder Settings.

Administrator Panel > Content Management > Content Management Settings > Virtual HardDrive

2. Select the availability of virtual hard drives. If virtual hard drives aremade available, select forwhich roles folders are created.

3. Set upDefault Folder Settings. This determines which folders will be created by default in theContent Collection, such as Course folders within the Courses directory for users with specificroles. It also allows the Administrator to set a quota for user folders.

Administrator Panel > Content Management > Content Area Management > Default FolderCreation Settings

4. Select Edit next to each top level folder. Set the permissions and default quotas for each top levelfolder. These options for top level folders may be changed in the future; however, changes will onlyaffect newly created folders.

5. Set thePrivacy Settings. This determines whether the Content Collection respects the user’sprivacy. Users have the option of choosing whether or not their user information is made public intheUser Directory of Blackboard Learn. ThePrivacy Settings page allows Administrators todetermine whether these privacy settings chosen by users will be respected during user searchesof the Content Collection.

Administrator Panel > Content Management > Content Management Settings > PrivacySettings

6. Enable theDeletion Audit Trail for the Document Stores. This setting tracks how long files willremain in the system before being permanently deleted. This log is stored in the database; thelifetimemay be set fairly high without affecting system performance.

Administrator Panel > Content Management > Technical Settings > Document Stores >Select Edit from the contextual menu and click Deletion Audit Trail Settings

7. Turn on theDeletion Audit Trail for each Document Store by entering the number of days fortheDelete Audit Trail Lifetime.

8. Enable persistent cookies. Using persistent cookies increases the usability of WebDAV; users willnot be asked to authenticatemultiple times.

Administrator Panel > Content Management > Technical Settings > Authentication Settings

How to Configure Full Text SearchConfigure full text search indexing options. This sets the time of day and the duration for the system to rebuildthe Full Text Search Indexes. It is recommended that the option be set to aminimum of one hour.Administrators may also choose to use the Immediate Update option, which will update the index as files areadded to the system. This settingmay impact performance.

Administrator Panel > Content Management > Technical Settings > Full Text Search SettingsIf the system has automated backup, check that the settings on the Full Text Settings page do not interferewith the backup.

How to Configure Display OptionsTheDisplay Options allow the Administrator to set up how the Content Collection appears to users.

Administrator Panel > Content Management > Display OptionsThe following areas must be configured inDisplay Options:


9.1 S

P6 BETA D

RAFT


l Content List Display Options: Set which features are available in the Action Bar, such as AddFolder and Copy. Determine which columns will appear, such as Display Size and DisplayPermissions.

l Menu Display Options: Choose how the left-hand navigationmenu appears to users.l Manage View Items: Customize the appearance of the Shortcut and Folder Views.

How to Enable Content Management FeaturesFollow the steps below to enable some of the features available in the Content Collection:

1. Make Portfolios available on the system. Select which roles have access to this feature.

Administrator Panel > Content Management > Portfolios > Portfolio Settings2. Modify Portfolio Templates to suit the Institution andmake them available.

Administrator Panel > Content Management > Portfolios > Personal Portfolio TemplatesAdministrator Panel > Content Management > Portfolios > Basic Portfolio Templates

3. Set the availability of eReserves.

Administrator Panel > Content Management > Content Management Settings > eReserves4. EnableWeb Folders.

Administrator Panel > Content Management > Feature and Tool Management >WebFolders

5. Enable the availability of the Learning Objects Catalog.

Administrator Panel > Content Management > Learning Objects Catalog > CatalogAvailability

6. Select CatalogManagers.

Administrator Panel > Content Management > Learning Objects Catalog > CatalogManagement Options

How to Enable Content Management Features in CoursesFollow the steps below to enable Content Management features available in Blackboard Learn Courses:

1. Allow Instructors to check links to Content Collection items within a Course. Set theCheckCourse Links tool toAvailable.Administrator Panel > Courses > Course Settings > Course Tools

2. Allows Instructors to copy files from aCourse to the Content Collection. Set theMove Files toCourse Files tool toAvailable.Administrator Panel > Courses > Course Settings > Course Tools

How to Access the Content CollectionOnce enabled, the Content Collection Tab will appear when a user logs into Blackboard Learn. TheAdministrator may access the Content Collection through this tab or through theManage Content option onthe Administrator Panel.

Setting Up Tomcat ClustersTomcat Application Clusters consist of multiple Blackboard Learn java application (JVM) server instancesrunning simultaneously (on the same physical server) and working together to provide increased scalability.


9.1 S

P6 BETA D

RAFT


Scalability is an application's ability to support a growing number of users. If it takes one application 10milliseconds to respond to one request, how long does it take to respond to 10,000 requests? If a user logs on at3 AM do they experience the same responsiveness as they do at 3 PM? Tomcat Application Clusters ensurethat Blackboard Learn remains responsive by adding server instances to a cluster without interruption ofservice.

Note: Cluster nodes cannot bemodified. If a change is required, then the nodemust be removed and thenadded again with the updated information.

Tomcat Application Clusters are not meant as a replacement for traditional load-balanced configurations, but asa complementary scheme that provides improved scalability and failover capabilities. Traditional load-balancingis a physical distribution of server instances across multiple servers. Tomcat Application Clusters are logicalinstances of the Java application components that reside on a single server, or are distributed across multipleservers.

There are two types of server clustering: horizontal and vertical:

l Horizontal clusters allow server instances to be deployed across multiple physical servers. Thismethod of clustering is not implemented by Blackboard because Blackboard already supports load-balancing.

l Vertical clusters, also known as multi-home clusters, allow multiple server instances to be run on asingle machine. This method takes full advantage of the processing power of a single server. Verticalclusters are load-balanced by the web server.

Tomcat Clustering runs on all Blackboard platforms (Windows, Linux, and Solaris).

Before Installing a Tomcat ClusterThe server must be configured to support clustering prior to installing a Tomcat Cluster node. Clustering isdisabled by default andmust be enabled. Installing a cluster requires that the application instance be shutdownand restarted.

Note: The following procedures assume that the Administrator has full administrative rights as eitheradministrator or root.

How to Configure a Windows Server1. Go to blackboard_home\config.2. Open the bb-config.properties file.3. Search for the bbconfig.tomcat.cluster.enable variable, andmodify the default value

from FALSE to TRUE.4. Open the context.xml file and uncomment the option to disable session persistence across

Tomcat restarts.5. Within the context.xml file, the listening port assigned to the Tomcat nodes must be different for

each node.6. Go to blackboard_home\tools\admin7. Run PushConfigUpdates to activate the changes. To learnmore, see PushConfigUpdates.8. Create a new ServerGroup in Blackboard Learn:

a. Navigate to blackboard_home\tools\admin.b. Create a ServerGroup with a specified port number by running

ServerGroupManager.bat -c -n new_group_name -p new_port_number.


9.1 S

P6 BETA D

RAFT


Note: In aWindows load-balanced environment, the PushConfigUpdates script must be run on each load-balanced server. To learnmore, see PushConfigUpdates. In addition, each Nodemust have its ownServerGroup.

How to Configure a UNIX Server1. Go to the Blackboard Learn home, blackboard_home/config.2. Open the bb-config.properties file.3. Search for the bbconfig.tomcat.cluster.enable variable, andmodify the default value



each node.6. Go to blackboard_home/tools/admin.7. Run PushConfigUpdates to activate the changes. To learnmore, see PushConfigUpdates.8. Create a new ServerGroup in Blackboard Learn:

a. Navigate to blackboard_home/tools/adminb. Create a ServerGroup with a specified port number by issuing

./ServerGroupManager.sh -c -n new_group_name -p new_port_number.

Note: In a UNIX load-balanced environment, the PushConfigUpdates script must be run on each load-balanced server. To learnmore, see PushConfigUpdates. In addition, each Nodemust have its ownServerGroup.

Installing a Tomcat ClusterNote: The following procedures assume that the Administrator has full administrative rights as eitheradministrator or root.

Upon creating an individual cluster node, the Blackboard services will need to be shut down and restarted toreset the configuration with the new clustered node.

Property Description

ClusterID

Must be a unique name with no spaces between any of the letters. Best practice is to identify onenaming convention for all nodes and increment numerically to differentiate servers and nodes.Example: Blackboard1 or Blackboard2.

ServerShutdownPort

Must be a unique port in order to connect to the JVM for the clustered node and shut it down. Bydefault the primary application server installed with Blackboard runs on port 8005, therefore a newvalue must be supplied to avoid port socket contention. Best practice is to increment the current servershutdown port by 1000.

JKConnectorPort

Must be a unique port in order for the web server to communicate to each clustered node. The defaultport is 8009. Best practice is to increment the current jk connector port by 1000.

ClusterListenerPort

Must be a unique port for the cluster to replicate session information across the wire. The default portis 4000. Best practice is to increment the current listen port by 1000.


9.1 S

P6 BETA D

RAFT


How to Install a Tomcat Cluster in Windows1. Launch the Install Cluster script by running the InstallCluster.batfile. After running the file,

you will be prompted for the following information. Configure the settings according to the previoustable.

a. Cluster ID

b. Server shutdown Port

c. JK Connector Port

d. Cluster Listener Port

2. Stop your server by running ServiceController.bat services.stop.3. Start your server by running ServiceController.bat services.start.

How to Install a Tomcat Cluster in UNIX1. Launch the Install Cluster script by issuing ./InstallCluster.sh.

After running the command, you will be prompted for the following information.

2. Configure the settings according to the previous table.a. Cluster ID

b. Server shutdown Port

c. JK Connector Port

d. Cluster Listener Port

3. Stop your server by issuing ./ServiceController.sh services.stop.4. Start your server by issuing ./ServiceController.sh services.start.5. Run the jps command from JAVA_HOME to see the bootstrap processes. You should see one

Tomcat Process, and the number of Cluster Process IDs.

Tip: UNIX customers should increase the Apache MaxClients value as they add nodes. Blackboardrecommends multiplying the initial value by the number of total JVMs. For example, if MaxClients is 500 for anon-clustered configuration, when 2 JVMs are added, this setting should increase to aminimum of 1500.

Files that are AffectedAfter a cluster is installed, a number of files and directories are produced. The following table highlights some ofthese files and directories.

Directory or File Description

blackboard_home/apps/tomcat/cluster/ A new directory that is created when the first node (other than root) isinstalled.

blackboard_home/apps/tomcat/cluster/node_id

A new directory that is created for every node added. Each directorycontains files affecting that node: …/conf/server.xml and log files.

blackboard_home/apps/tomcat/conf/jk/workers.properties

This file exists before adding a node but changes whenever a nodeis added to include load-balancing information for that node. Tolearn more about the workers.properties file, seehttp://tomcat.apache.org.

server.xml A file that allows you to configure Tomcat nodes through the use ofXML descriptors.


9.1 S

P6 BETA D

RAFT

http://tomcat.apache.org/tomcat-3.3-doc/Tomcat-Workers-HowTo.html


Troubleshooting Installation IssuesThe following are the steps to take if the Tomcat Cluster is not functioning as expected.

1. Check that the following value is present and set to TRUE in the bb-config.properties filelocated in blackboard_home/config: bbonfig.tomcat.enable=true

If it is set to false, then run PushConfigUpdates to activate the changes. To learnmore, seePushConfigUpdates. For additional information, see Before Installing a Tomcat Cluster.

1. Check that the workers.properties file contains the correct information for all of the nodesinstalled in the cluster. To learnmore about the workers.properties file, see Files that areAffected.

2. Watch the Java processes running on your application server. A Java process should be runningfor each node installed and one for the root node. CPU processing should be distributed across thenodes.

Enabling Cache ReplicationBy default, Blackboard Learn will install with cache replication in a cluster disabled. To enable replication, youmust manually configure the setting and restart your application servers.

How to Enable Cache Replication in Windows1. Go to blackboard_home\config\internal\.2. Open the ehcache.xml file.3. Search for the two cacheManagerxxx elements and remove the comments.4. Additional information, specific to the elements, is located within the ehcache.xml file.5. Stop your server by running ServiceController.bat services.stop.6. Start your server by running ServiceController.bat services.start.

How to Enable Cache Replication in UNIX1. Go to blackboard_home/config/internal/.2. Open the ehcache.xml file.3. Search for the two cacheManagerxxx elements and remove the comments.4. Additional information, specific to the elements, is located within the ehcache.xml file.5. Stop your server by issuing ./ServiceController.sh services.stop.6. Start your server by issuing ./ServiceController.sh services.start.

After restarting, all caches that aremarked asbbconfig.cache.(cachename).needsclusterinvalidation=true in cache-settings.properties will send invalidation notifications to all nodes in the system when entries areremoved/flushed/updated.

Removing a Cluster NodeNote: The following procedures assume that the Administrator has full administrative rights as eitheradministrator or root.

Upon removing an individual cluster node, the Blackboard services will need to be shut down and restarted toreset the configuration without the clustered node.


9.1 S

P6 BETA D

RAFT


How to Remove a Cluster Node in Windows1. Go to blackboard_home\tools\admin.2. Stop your server by running ServiceController.bat services.stop.3. Launch the Remove Cluster script by running RemoveCluster.bat.4. Specify the cluster to be deleted when prompted.5. Start your server by running ServiceController.bat services.start.

How to Remove a Cluster Node in UNIX1. Go to blackboard_home/tools/admin2. Stop your server by issuing./ServiceController.sh services.stop .3. Launch the Remove Cluster script by issuing ./RemoveCluster.sh.4. Specify the cluster to be deleted when prompted.5. Start your server by issuing ./ServiceController.sh services.start.6. Verify the cluster was successfully removed by running the jps command from JAVA_HOME to

see the bootstrap processes.

Best PracticesFor information about optimizing Blackboard Learn to perform best in a particular environment, see AboutOptimizing Blackboard Learn.

Setting Up LDAPThis topic provides an overview of the LDAP Installation process. This process consists of a set of steps thatwill enable the administrator to use LDAP authentication.

LDAP ConfigurationThe following steps outline the LDAP configuration process:

1. Edit the /blackboard_home/config/authentication.properties file. See the nexttopic, LDAP Property Configuration for specific information on the properties and possible values inthis file.

2. Configure the bbconfig.auth.type property to LDAP. This must be done for the configurationto proceed correctly. Make the following change in the bb-config.properties file:

bbconfig.auth.type=ldap

3. Run PushConfigUpdates to activate the changes. To learnmore, see PushConfigUpdates.

Open LDAP – UNIX Operating Systems OnlyBlackboard has two versions of LDAP client authenticationmodules, the default andOpenLDAP.

Twomodules exist because the default LDAP client does not release file descriptors when it is under heavyload. A file descriptor is used by UNIX Operating Systems to keep track of open files and networkconnections. If the system continually accumulates file descriptors, the server will reach amaximum number ofallowed file descriptors, at which point nomore files can be opened and nomore network connections can beaccepted.


9.1 S

P6 BETA D

RAFT


Administrators of UNIX Operating Systems who experience this file descriptor issue under heavy loadmaydeploy OpenLDAP as a workaround.

If OpenLDAP is used, the .jar files must be updated so the command line tools do not fail. A copy of the jar fileshould be in /systemlib.

Additionally, edit /system/build/bin/launch-tool.sh and append the .jar files to the BB_CP variable.Otherwise, command line tools that bootstrap the core services (for example, LogRotation orPurgeAccumulator) will not work.

Setting Up a Proxy ServerSome Institutions require an outbound proxy server to comply with government regulations or Institutionpractices. Blackboard Learn allows the use of an outbound proxy server to secure communications. Inparticular, the proxy server works with Course Cartridge downloads and RSS feeds incorporated intocommunity modules.

Configure the Proxy Server for UNIXFollow these steps to configure Blackboard Learn to use an outbound proxy server.

1. Install the proxy server according to the Institution standards.2. Open the /blackboard_home/config/bb.config.properties file.3. Add the domain name or IP address of the proxy server to the

bbconfig.webserver.ouboundproxyurl property.4. Save the file.5. Run PushConfigUpdates to activate the changes. To learnmore, see PushConfigUpdates.

Configure the Proxy Server for WindowsFollow these steps to configure Blackboard Learn to use an outbound proxy server.

1. Install the proxy server according to the Institution standards.2. Open the C:\blackboard_home\config\bb.config.properties file.3. Add the domain name or IP address of the proxy server to the

bbconfig.webserver.ouboundproxyurl property.4. Save the file.5. Run PushConfigUpdates to activate the changes. To learnmore, see PushConfigUpdates.

Using ServicesAfter Blackboard Learn is installed, it adds the bb-collab and bb-tomcat services to the operating system.In addition, for Blackboard Learn to run properly onWindows, the IIS servicemust be running and the SQLServer databasemust be started. When running on a UNIX operating system, the Apache process must berunning and theOracle databasemust be started and running correctly. When performingmaintenance orupgrade tasks it may be necessary to stop some of these services.

For most upgrade tasks, including installing Blackboard Learn software updates, the bb-collab, bb-tomcat, and IIS or Apache services should be stopped but the database should be running. While this is agood general rule, please refer to the specific instructions for each task to confirm.

Blackboard uses the "service" terminology familiar toWindows users. UNIX users should think of services asprocesses.


9.1 S

P6 BETA D

RAFT


Definition of Blackboard Servicesbb-collab: The bb-collab service runs the Collaboration Tool within Blackboard Learn. Stopping thisservice will make the Collaboration Tool unavailable to users.

bb-tomcat: The bb-tomcat service runs the Java® servlet engine. Stopping this servicemakes any Javaservlet pages unavailable to users, including the Login page.

Starting and Stopping ServicesThe ServicesController utility is used to start and stop services. This utility must be run from thecommand line.

WindowsC:\blackboard_home\tools\admin\ServiceController argument

UNIX/blackboard_home/tools/admin/ServiceController argument

The following table describes the available argument options.

Argument Description

services.start Starts all the services related to the Blackboard Learn.

services.stop Stops all the services related to the Blackboard Learn.

services.restart Stops and immediately starts the services related to the Blackboard Learn.

services.appserver.start Starts the bb-tomcat service.

services.appserver.stop Stops the bb-tomcat service.

services.appserver.restart Stops and immediately starts the bb-tomcat service.

services.webserver.start Starts the IIS or Apache® Web service.

services.webserver.stop Stops the IIS or Apache Web service.

services.webserver.restart Stops and immediately starts the IIS or Apache Web service.

Starting and Stopping the bb-collab ServiceIn rare instances it may be necessary to stop only the bb-collab service but leave all other services running.For example, when setting up a dedicated collaboration server in amultipleWeb/app server configuration it isnecessary to stop the bb-collab service on all servers except the collaboration server.

The bb-collab service (as well as the IIS and bb-tomcat services) can be controlled individually throughthe Services panel onWindows operating systems. UNIX operating system users employ UNIX commandsthat control processes tomanage the bb-collab and apache services.


9.1 S

P6 BETA D

RAFT


Glossary of TermsTerm Definition

Active A Blackboard Learn record in active state appears in the database and within the application.

API Application Programming Interface. An API is code within an application that is revealed to allowprogrammers to create software that interacts with the application.

Available A Blackboard Learn active record that is available and can be managed and manipulated withinBlackboard Learn. For example, a Course that is available can be accessed by all users with a rolein that Course.

Batchoperation

Processes several data records at once.

Batch UID An attribute, or attributes, that are unique to each record within a data entity.

Change Key Event Driven API persistence action. Changes the unique identifier for a person or group. Thechange will be reflected in any membership records as well.

ConcreteData Typesand AbstractData Types

Concrete data types, such as Courses and users, appear within Blackboard Learn. Abstract datatypes, such as group or person are IMS standards that relate to concrete, Blackboard Learn datatypes.

Course A data entity where each record consists of an individual Course. Attributes identify details about theCourse, including: Course Name, Course ID, and descriptive information.

CourseCategory

A data entity where each record consists of a Course catalog category. Attributes include a categoryname, a category key called a mnemonic, and the availability of the category.

CourseCategoryMembership

A data entity where each record connects a Course to a Course catalog category. Course CategoryMemberships are identified by a composite primary key composed of the Course ID and thecategory key.

Dataattribute

A type of data that may be shared by the records in an entity. If viewing an entity as a table, anattribute is an individual column.

DataOwnership

Data attributes are owned by the institution information system or by Blackboard Learn. If a dataattribute is owned by Blackboard Learn, than a difference between the feed file and the BlackboardLearn database is ignored during a Snapshot operation.

Data SourceManagement

Identifies external data sets. All data that is integrated with Blackboard Learn is tagged with anidentifier that groups it with a logical set of data. The Data Source Management Tool can be used tonot only identify, but to create a sophisticated management system to handle the interactionbetween the institution’s information systems and Blackboard Learn.

Deleted A deleted record has been removed from Blackboard Learn. The term “deleted” is used with theterm “purged” interchangeably.

Disable Event Driven API persistence action. Puts a record into disabled state.

Disabled A Blackboard Learn record in disabled state still exists in the Blackboard Learn database but doesnot appear within the application.

Entity A group of data records that share the same attributes. Each record is unique and identified by akey.

Field A field within Blackboard Learn is any item that accepts input from the user. Information entered intoa field within the application is stored as an attribute within the database.

Group IMS data entity that is represented by the Course and Organization entities in Blackboard Learn.

GroupMembership

IMS data entity that is represented by the Student Enrollment, Staff Student, and OrganizationMembership entities in Blackboard Learn.


9.1 S

P6 BETA D

RAFT


Term Definition

Insert Event Driven API persistence action. Inserts a record into the Blackboard Learn database.

ManualMode

The feed file is processed and each record is either inserted or updated. If a record appears withinBlackboard Learn and not in the feed file, it is not changed. Manual mode is often used to explicitlyperform an insert or update of a small number of records, unlike snapshot mode, where data isreconciled between Blackboard Learn and the institution’s information system.

Object An object is an instance of a java class that contains both data attributes and methods for handlingthe data.

Organization A data entity where each record consists of an individual an Organization. Attributes identify detailsabout the Organization, including: Organization Name, Organization ID, and descriptive information.

OrganizationCategory

A data entity where each record consists of an Organization catalog category. Attributes include acategory name, a category key called a mnemonic, and the availability of the category.

OrganizationCategoryMembership

A data entity where each record connects an Organization to an Organization catalog category.Organization Category Memberships are identified by a composite primary key composed of theOrganization ID and the category key.

OrganizationMembership

A data entity where each record consists of a user’s participation in a Course. OrganizationMembership records are identified by a composite primary key composed of the user ID and theCourse ID.

Persister Objects that control the data input into Blackboard Learn as part of the Data Integration process.

Person IMS data entity that is represented by the User entity in Blackboard Learn.

Purged A purged record has been removed from Blackboard Learn. The term “purged” is used with the term“deleted” interchangeably.

Record An item within an entity that contains the attributes of that entity. Viewing an entity as a table, arecord would be an individual row within that table.

Remove Event Driven API persistence action. Deletes records from the Blackboard Learn database.

RemoveMode

The records in the feed file are permanently deleted from Blackboard Learn. In addition, anyassociated records, such as enrollments or category links, are deleted as well.

Right to Left Languages such as Arabic and Hebrew are aligned right to left.

Save Event Driven API persistence action. Updates a record if it exists. If it does not, the record is insertedinto the Blackboard Learn database.

SmartUpdate

Synonymous with manual update, a smart update inserts or updates but does not change recordsthat exist in the Blackboard Learn database that are not in the feed file.

Snapshot The Snapshot process takes a feed file generated from another of the institution’s informationsystems and processes the data within Blackboard Learn.

SnapshotController

The Snapshot Controller automates and manages the snapshot process after the SnapshotGenerator creates a feed file. Like the Snapshot Generator, the institution must write the SnapshotController.

SnapshotGenerator

Software, written by the institution, which generates flat files or XML files from another of theinstitution’s information systems.

SnapshotMode

The feed file is processed and each record is inserted, updated, or disabled.

Staff Student A data entity where each record consists of a staff member’s participation in a Course. Staff Studentrecords are identified by a composite primary key composed of the User Name and the Course ID.The user’s role in the Course must be identified in the record.


9.1 S

P6 BETA D

RAFT


Term Definition

StudentEnrollment

A data entity where each record consists of a Student’s participation in a Course. Studentenrollment records are identified by a composite primary key composed of the User Name and theCourse ID.

Unavailable A Blackboard Learn active record that is unavailable will appear within the Blackboard Learn,however, only users with certain roles can see it. For example, a Course that is unavailable will notappear to Students, but administrators and Instructors assigned to the Course can view the Course.

Update Event Driven API persistence action. Updates a record in the Blackboard Learn database.

User A data entity where each record consists of an individual user. Attributes identify details about theuser, including: user ID, user role, contact and other personal information.


9.1 S

P6 BETA D

RAFT

About the Installation Process > Fresh Installations

About the Installation Process

Fresh InstallationsIf this is the first time you have installed Blackboard Learn, make sure to read the Release Notes for the releasethat you are installing and any subsequent Service Packs, and then read this section carefully. After reading theRelease Notes and this section, you should be able tomake informed decisions about the configuration ofBlackboard Learn at your institution. The next step will be to read the configuration and installation instructionsappropriate for the host environment: Windows® or UNIX®.

If you are an experienced Blackboard Learn administrator, you will find some helpful information in this section.After a quick review, proceed to the configuration and installation instructions appropriate for your hostenvironment.

UpgradesIf you are upgrading from a previous version of Blackboard Learn, see the Upgrade section.

Getting Started

About the Installation Process

Fresh InstallationsIf this is the first time you have installed Blackboard Learn, make sure to read the Release Notes for the releasethat you are installing and any subsequent Service Packs, and then read this section carefully. After reading theRelease Notes and this section, you should be able tomake informed decisions about the configuration ofBlackboard Learn at your institution. The next step will be to read the configuration and installation instructionsappropriate for the host environment: Windows® or UNIX®.

If you are an experienced Blackboard Learn administrator, you will find some helpful information in this section.After a quick review, proceed to the configuration and installation instructions appropriate for your hostenvironment.

UpgradesIf you are upgrading from a previous version of Blackboard Learn, see the Upgrade section.

Preferred Technical SkillsInstalling and supporting a Blackboard installation hosted at the institution requires some specific technicalskills. It is important that human resources that understand the installation and support of enterprise softwareare available to install andmaintain Blackboard Learn.

Before attempting to install, ensure that the appropriate skill sets are available to support the installation andmaintenance of Blackboard Learn.

Database SkillsThe following database skills are recommended for installing andmaintaining Blackboard Learn.


9.1 S

P6 BETA D

RAFT





About the Installation Process > Getting Started

l Experience with Microsoft SQL Server or Oraclel Accessing and running SQL scriptsl Performing online and offline database backup and restorel Monitoring and reconfiguring database parameters tomeet growing demandl Tuning the performance of the host machine and the database server

Network SkillsThe following networking skills are recommended for installing andmaintaining Blackboard Learn.

l Troubleshooting network bottlenecksl Knowledge of authentication and experience with institutional authenticationmethods (LDAP,

Microsoft Active Directory®, or similar method)l Experience supporting 24/7 network environments with failover contingenciesl Experience configuring load-balanced solutions

Operating System and Application Server SkillsThe following operating system and application server skills are recommended for installing andmaintainingBlackboard Learn.

l Experience with Microsoft IIS® or Apache™l Experience with the operating system including file management and permissionsl Experience with optimization andmonitoring techniquesl Comfortable using a text editor to make changes to configuration filesl Experience installing softwarel Starting and stopping applications on the server to avoid damaging or corrupting the workstation or

databasel Creating scheduled jobs to automate system processes such as backup and log file managementl Installing and troubleshooting operating systemsl Comfortable using the command line interfacel Knowledge of how application servers work and how to start and stop the various servers and system

processesl Knowledge of how to add hardware to the serverl Performing tape backups and tape archive programs and understand how to use these backup tools

to move files around the system and betweenmachinesl Experiencemanagingmultiple points of integration

Developer SkillsThe following skills are recommended to create Blackboard Building Blocks or to use the Event-Driven API.

l Knowledge of compiling softwarel Experience with relational databasesl Experience with Java development at themid to senior programmer levell Experience programming Java Server pagesl Experience with JDBC™2.0l Experience with Java™SE


9.1 S

P6 BETA D

RAFT


l Experience with Connection poolingl Creating and testing JSPsl Experience with object-oriented programming

About the Blackboard Learn Installer and UpdaterThe Blackboard Learn Installer and Updater scans the server and either installs a new installation of BlackboardLearn or updates an existing installation. The Installer and Updater also handles the capabilities that yourschool can license with Blackboard Learn.

l Course deliveryl Community engagementl Content managementl Outcomes assessment

The features related to these capabilities are installed or updated based on the license file. This means that allusers follow the same install and update procedures regardless of which capabilities your school licenses.

The Installer and Updater Are One ToolInstall and update tasks are accomplished using the same tool. When this tool is referred to as the Installer, it isdescribing how the tool functions when installing software for the first time. When this tool is referred to as theUpdater, it is describing how the tool functions when it is run on an existing installation.

Update ProcessThe Installer and Updater will update the system when run on an existing installation. Updates are used toinstall:

l New releases: Set of fixes andmajor new functionsl Application Packs: Set of fixes and someminor new functionsl Service Packs: Small set of fixesl Hotfixes: From time to time, Blackboard will release hotfixes to address specific issues. Hotfixes are

usually so limited in scope that they do not use the Installer and Updater tool, but there areexceptions.

The update will include all previous updates, hotfixes, and service packs into one package.

What the Installer and Updater Can DoThe Installer and Updater can install set of capabilities in Blackboard Learn. It can be run on single-server, dual-server, and load-balanced configurations. The Installer and Updater can be runmore than once. If stopped, theInstaller and Updater must be restarted from the beginning.

The Installer and Updater presents several options when it is run on an existing installation:

l Update: Installs the new features and fixes associated with a new release. An error message willappear if it is not possible to update from the current version to the Updater version.

l Pre-Update Change Report: Reviews the current system configuration to ensure that the Updatercan be run successfully. The Pre-Update Change Report also details the files that will be changed bythe Updater.

l Provide New License: This option processes a new license file for the system. It is used to licenseadditional capabilities or change the licensing of current capabilities.


9.1 S

P6 BETA D

RAFT


l Uninstall: This option removes Blackboard Learn capabilities.l Uninstall App Server Only: This option removes Blackboard Learn capabilities from a dedicated

App Server in a load-balanced installation. It does not remove the database or shared file system. Itdoes not remove any software from the other App servers.

WARNING! When providing a new license, downtime is required. This installation option will perform a fullupgrade, shutting down services.

What the Installer and Updater Cannot DoThe Installer and Updater cannot be used to return to an earlier release. Running the Installer of an earlierversion on a newer installation will not successfully convert the installation to the earlier release.

The Installer and Updater does not install any other software, including prerequisite operating systems anddatabases. For example, Blackboard Learn - Basic Edition clients must first install Small-Scale Oracle,provided by Blackboard, before running the Installer and Updater. To learnmore about Small-Scale Oracle, seeAbout Small-Scale Oracle.

The Installer and Updater does not install supplemental tools such as OptiSERV or EnviSERV forcommunicating with the Blackboard Transact and the Snapshot Tools for integration with other informationsystem on campus. These tools must be downloaded and installed separately.

Finally, the Installer and Updater does not allow for any advanced configuration such as setting up LDAPAuthentication, SSL, or Virtual Installation. To learnmore, see Using Blackboard Learn Authentication, AboutSSL and SSLChoice, and Virtualizing the Blackboard Reference Architecture .

Understanding the Database Schema

Database Schema NamingDatabase schema names have received a re-work for this latest version of Blackboard Learn. When upgradingan existing instance, or creating a testing environment for an institution using the legacy database schemanames, please refer to the following table. Manual database schema name changes on an existing schemashould only be done with the assistance of Blackboard support. Legacy environments should specify thelegacy information within the database identifier option in the installer when creating testing environments.

Schema Name Legacy Schema Name

BBLEARN BB_BB60

BBLEARN_ADMIN BBADMIN

BBLEARN_STATS BB_BB60_STATS

CMS_DOC CMS_FILES_*

The Database Statistics SchemaThe activity_accumulator_cr procedure has beenmodified to insert new records into the new tableactivity_accumulator_queue instead of directly into the activity_accumulator table. The newtable will be smaller in size, which reduces the performance impact of activity_accumulator_cr, whichruns for every user action. Use of indexes on activity_accumulator_queue table should be avoided inthe interest of application performance.

A job has been scheduled via the Oracle DBMS_JOB interface to run a stored procedure activity_accumulator_update which flushes the queue table every 10minutes into the actual activity_


9.1 S

P6 BETA D

RAFT


accumulator. The activity_accumulator_update copies data from the queue table to activity_accumulator, which is the production table that holds the data permanently. This job inserts data in 2000-record batches to the activity_accumulator (though it leaves between 500-2000 records behind eachtime). Between the hours of 23:00 and 00:00 each night, database time, the jobmoves a higher volume of datato clean up any missed records from previously.

The activity_accumulator table contains attendance/activity data which is used by many institutions aspart of grading information, and is thus among themost important data in the database. It is crucial that thistable be recoverable in the event of media failure. Though the insertion and deletion are performed at the sametime, with the insert taking place first, the data is still available in the queue table and available for the next pushshould a rollback be required. Given the importance of this data, logging is enabled should an incident occur inan incorrectly configured Database or other disaster recovery need arise.

The PurgeAccumulator job is unchanged and still runs at 1:00 am every day to perform its three functions ofsummarize (system tracking), synchronize (BBLEARN to BBLEARN_STATS), and purge (BBLEARN).

Note: If the Oracle parameter job_queue_processes is set to zero, the activity_accumulator_update job will not run. As a symptom, the system tracking pages would start showing zeros and courseactivity reports would show no activity.

Statistics Schema DecouplingThe statistics schema BBLEARN_STATS can bemoved to a separate database or physical system, andsettings will be preserved when running PushConfigUpdates. The values in BBLEARN_admin.BB_INSTANCE are populated from bbconfig.database.stats.server.name in bb-config.properties. This performance enhancement benefits clients who useManaged Hosting, as wellas those with sophisticated datamanagement needs.

Understanding Load BalancingBlackboard Learn supports installation across multiple application servers with a hardware load balancer or asoftware solution. Blackboard Learn performance is better when the servers are dedicated to Blackboard Learnprocesses and requests. Using a software solution for load-balancing puts additional strain on the processorsas load-balancing is handled by the application servers, not by a separate piece of hardware.

Load Balanced ConfigurationsThe following diagram shows an example of amultiple application server configuration.


9.1 S

P6 BETA D

RAFT


Multiple Application Server Configuration

Load-balanced configurations includemultiple application servers, a database server (or failover cluster), a filesystem server, and a Collaboration Tool server. Select one of the existing application servers to also act as theCollaboration server. The Collaboration server may not be spread across multiple application servers becauseall users participating in a Collaboration sessionmust share the same resources. A hardware load-balancer isoptional. Using a hardware load-balancer is the preferredmethod of load-balancing. A network switch is used tohandle communications from the client machines to the application servers and the Collaboration server. Aseparate switch is used to handle a secure, private connection between the application servers and the filesystem and database servers. The database and file systemmust be on a secure, private network.

The diagram also shows integration with an LDAP server or servers to handle authentication and an SISsystem to share data with Blackboard Learn. Integrating these components with a load-balanced configurationis not difficult, but does require eachWeb/application server to share the same settings.

Finally, the diagram shows a Storage Area Network (SAN) device and a backup device. A SAN device is notrequired but many institutions choose to use one. Regular, frequent data backup and consistent recoveryprocedures are critical parts of any Blackboard Learn configuration. The diagram shows a tape drive backup butany backupmethodmay be used that meets the needs of the institution.

Benefits of Scaling Out with Additional Web/Application ServersScaling out distributes the computing workload amongmultiple servers by clustering or load balancing, with theability to add servers to increase capacity. By distributing the workload, processing resources are spreadamongmultiple servers, which improves both performance and the availability of the overall service.

Down time is reduced with a scale out approach becausemost single points of failure are removed. If a servergoes down, other servers pick up the load dynamically, allowing the application to continue servicing clients.

To learnmore about configuring a Blackboard Learn environment to achieve the best performance possible, seethe PerformanceOptimization topics.

Defining the Host EnvironmentBefore installing the Blackboard Learn software, it is necessary to create a healthy environment to hostBlackboard Learn. At this stage, decisions include determining the number of servers, the operating systemand database software to use, how powerful the servers must be, the appropriate amount of disk space, andwhether the network is capable of handling the anticipated traffic.

Read the Hardware Sizing InformationAbout Hardware Sizing in a Dell Environment and About Hardware Sizing in a SunMicrosystems Environmentprovide detailed information about choosing the appropriate hardware based on size, scalability, performance,and redundancy needs. Read the appropriate section of the help before continuing.

Choose an Operating SystemBlackboard supports operating systems from three vendors for hosting Blackboard Learn:

l Microsoft Windows Server®l RedHat Enterprise Linux®l Sun Solaris™

For the exact versions of the databases that are supported, see "Supported Technologies" in the ReleaseNotes for the release that you are installing. It is critical that the operating system used to host Blackboard


9.1 S

P6 BETA D

RAFT

../../../../../Content/Mini_TOCs/mt_admin_server_system_optimize.htm

../../../../../Content/Mini_TOCs/mt_admin_server_system_optimize.htm




Learn is a supported or compatible operating system. It is critical that the operating system used to hostBlackboard Learn is a supported or compatible operating system.

SPARC hardware is required for to install and run Blackboard Learn under Solaris operating systems.

Choose a DatabaseThis is an easy decision after selecting the operating system because Blackboard supports only one databasefor each supported operating system. Blackboard supports Microsoft SQL Server®, Enterprise Edition, whenBlackboard Learn is hosted on aWindows operating system (the Standard Edition is compatible withBlackboard Learn). Blackboard supports anOracle® database when Blackboard Learn is hosted on a Red HatEnterprise Linux or Sun Solaris operating system.

When Blackboard Learn - Basic Edition is hosted on a Red Hat Enterprise Linux or Sun Solaris operatingsystem, Blackboard provides a special version of Oracle called Small-Scale Oracle. Small-Scale Oracle is theonly database supported for Blackboard Learn - Basic Edition when hosted on a Red Hat Enterprise Linux orSun Solaris operating system. To learnmore about Small-Scale Oracle, see About Small-Scale Oracle.

When Blackboard Learn - Basic Edition is hosted on aWindows operating system, the supported version ofMicrosoft SQL Server must be used.

For the exact versions of the databases that are supported, see "Supported Technologies" in the ReleaseNotes for the release that you are installing.

Decide the Number of ServersRead About Hardware Sizing in a Dell Environment or About Hardware Sizing in a SunMicrosystemsEnvironment to determine hardware requirements for the installation. For the purposes of running the Installer,match the hardware to one of the followingmodels:

l One server: This configuration hosts Blackboard Learn application software, file system, anddatabase on onemachine. Keep inmind that a one server configuration is appropriate for running atest system or Blackboard Learn - Basic Edition. Blackboard Learn - Basic Edition can be run only onone server.

l Two servers: This configuration hosts Blackboard Learn application software with the file system ononemachine and the database on another machine. This configuration is appropriate for institutionswith a smaller user base that do not need the performance or redundancy of a load-balancedconfiguration.

l Load-balanced: This configuration hosts the file system on onemachine, the database on anothermachine, and the application software is replicated onmultiple machines to handlemore activity. Thisconfiguration offers the greatest scalability and redundancy.

Database ClusteringSome institutions may require database clustering as a redundancy to ensure that the system is alwaysavailable, even in the event of a database server crash.

ForWindows, Blackboard supports installation on aMicrosoft SQL Server Failover configuration. To learnmore, see Set Up Database Clustering and Storage forWindows.

For UNIX, Blackboard offers support for Oracle RAC with all versions of Oracle supported by Blackboard. Tolearnmore, see Set Up Database Clustering and Storage for UNIX.

File System Storage and Database File StorageIn many instances, it is useful to store data, such as the files uploaded to a Course, on separate storagehardware. To learnmore, see Set Up File System Storage forWindows or Set Up File System Storage for


9.1 S

P6 BETA D

RAFT




UNIX. This is handled at the operating system level by pointing some directories or all directories to a separatestorage device. Likewise, it is possible to offload storage of the database files to a separate hardware, such asa SAN.

Collaboration ServerBlackboard Learn includes features for synchronous communication such as a Chat Tool and aWhiteboardTool. These features are wrapped into the Collaboration Tool available within Courses. The Collaboration Toolcommunications are handled by a dedicated service that requires its own ports.

Select one of the existing application servers to also act as the Collaboration server. The Collaboration servermay not be spread across multiple application servers because all users participating in a Collaboration sessionmust share the same resources. A single server must be configured to run the Collaboration server. This servermust handle Collaboration sessions and performance will be unaffected by other requests. The applicationservers are configured to connect users to one server that handles all the Collaboration sessions.

During installation, it is possible to specify that a separatemachine will handle all Collaboration Toolcommunications. This requires that either an existing application server be dual-purposed, or a dedicated serverbe configured to host the Collaboration server. Those institutions running Blackboard Learn on just one or twoservers, obviously would never opt to create a dedicated Collaboration server, and instead dual-purpose theexisting application server. To learnmore, see Set Up a Collaboration Server forWindows in a Load-BalancedConfiguration or Set Up a Collaboration Server for UNIX in a Load-Balanced Configuration. With the exceptionof that topic, all references to a Collaboration Server assume that your environment is using a single existingapplication server that has been dual-purposed as the Collaboration server.

Do not connect the Collaboration server to the load balancer.

Next StepsThe decisions that define the host environment guide the installation process. The next step before running theInstaller is configuring the environment. The following table outlines the configuration path to follow for eachpossible configuration:

Operating System and DatabaseNumber ofServers Refer to Topic

Microsoft Windows and SQL Server One Install on Windows on One or Two Servers

Two Install on Windows on One or Two Servers

Load-Balanced Install on Windows in a Load-BalancedConfiguration

Red Hat Enterprise Linux and Small-ScaleOracle

One Install on UNIX on One or Two Servers

Sun Solaris and Small-Scale Oracle One Install on UNIX on One or Two Servers

Red Hat Enterprise Linux and Oracle One Install on UNIX on One or Two Servers

Two Install on UNIX on One or Two Servers

Load-Balanced Install on UNIX in a Load-BalancedConfiguration

Sun Solaris and Oracle One Install on UNIX on One or Two Servers

Two Install on UNIX on One or Two Servers

Load-Balanced Install on UNIX in a Load-BalancedConfiguration


9.1 S

P6 BETA D

RAFT


Planning the InstallationThis topic covers some issues that may need to be addressed while planning and preparing for BlackboardLearn. Each school or institution that uses Blackboard Learn is unique and will require specific and detailedplanning to implement Blackboard Learn. The information in this topic should not be viewed as standard andcomprehensive but rather as a set of items that should be considered and adapted to each institution.

Develop a Learning ModelBefore installing Blackboard Learn or making it available to users, it is important to define how it will be used atthe institution. Having a sound plan for how Blackboard Learn will be used helps ensure that configuration andsecurity decisions are aligned with the goals of the institution. Some items to consider include:

l Define a naming convention for Courses and users on the system.l Determine what information and areas of the system are accessible to each set of users (Instructors,

Students, Guests, and so forth). If your school licenses community engagement, Administratorshave the flexibility to present different brands and content to users depending on their assignedInstitution Roles. Institution Roles are defined by the institution tomatch their organization.

l Identify the other information systems will interact with Blackboard Learn. Define which system ownsthe data.

l Build a team tomanage the system, support users, and develop tools and content.

These are just a few examples of the decisions that go into developing a learningmodel. Each institution willhave a unique approach appropriate for its users.

Create a Test EnvironmentCreating a test environment is a critical step in the process. A test environment allows system and databaseadministrators to tune the software for maximum performance based on the needs of the institution. Developersuse the test environment to build System Extensions prior to rollout as well as developing tools for integratingwith other information systems at the institution.

Finally, a test environment helps resolve potential issues with hardware or software before rolling outBlackboard Learn to users.

Establish a Support InfrastructureHaving qualified, trained staff to support users is important to operating smoothly with little interruptions tousers. Define what level of support is required and when it should be available to users. Some institutions mayrequire 24/7 support while others can operate with less. After training staff and defining support availability andexpectations be sure to communicate this information to users.

Run a Pilot ProgramAfter the software is installed, configured, and tested and the support staff is trained, it is a good idea to launcha pilot program. A pilot program lets a few users on the system to work with the software in the context of thelearningmodel. This is a good time to spot roadblocks or issues that may impact users when the software isrolled out. Also, the pilot program participants (especially the Instructors) can take a leadership role among theirpeers when the software is rolled out. These users can train other users on the software and help themsuccessfully adopt the learningmodel.


9.1 S

P6 BETA D

RAFT

About the Installation Process > Windows

RolloutWhen Blackboard Learn is ready for users, it is important to communicate key information to users. Make surethat the user base has access to training sessions, support, and other resources to help them begin using thesystem.

Windows

Install on Windows on One or Two ServersThis section explains the required hardware, software, and necessary steps to properly install BlackboardLearn on one or twoWindows servers.

1. Set Up the Hardware and Software2. (Optional) Set Up Database Clustering and Storage3. (Optional) Set Up File System Storage4. Complete the Pre-Installation Checklist5. Complete the Pre-InstallationWorksheet6. Install the Blackboard Learn Application Server and Database

Set Up the Hardware and Software on Windows on One or Two ServersThis section reviews the configuration steps necessary before installing Blackboard Learn.

Required HardwareAbout Hardware Sizing in a Dell Environment and About Hardware Sizing in a SunMicrosystems Environmentdetail several different hardware configurations based on performance, cost, and redundancy. Make sure thatthe planned hardware configurationmeets the needs of the institution.

Required SoftwareFor the exact versions of the operating systems, databases, and Java SE Developers Kit (JDK™) that aresupported, see "Supported Technologies" in the Release Notes for the release that you are installing. It iscritical that the software used to host Blackboard Learnmeets requirements.

The supported version of the JDK can be downloaded at http://java.sun.com/javase/downloads/index.jsp.

If installing onmultiple servers, download and install the JDK on each application server.

Make sure that the server or servers are dedicated to Blackboard Learn. Make sure that the server is not usingvaluable space and resources running unnecessary applications.

Set JAVA_HOMEThe correct version of the JDK must be installed on the application server and the JAVA_HOME environmentvariable must be set. The JDK installer first installs the JDK, and then installs the Java Runtime Environment(JRE). Ensure that these are installed to different locations and that the JRE installer is not allowed to overwriteportions of the JDK.


9.1 S

P6 BETA D

RAFT



http://java.sun.com/javase/downloads/index.jsp


IMPORTANT! Make sure that the path to the JDK does not include any spaces. For example, do not useC:\Program Files\Java\jdk1.6.0_18. Instead, use C:\Java\jdk1.6.0_18.

Follow these steps to set the JAVA_HOME environment variable:1. Make sure that the correct version of the JDK is installed on the application server.2. Right-click Computer and select Properties.3. Click Advanced System Properties.4. Click Environment Variables.5. In the system variables list, find JAVA_HOME and click Edit. If JAVA_HOME does not exist in the

system variables list, click New. A pop-up window will appear. TheVariable name should readJAVA_HOME.

6. Enter the full path to the JDK in theVariable value field. For example, C:\Java\jdk1.6.0_18.7. Click OK.

Note: Click paths forWindows 2003 and SQL 2005 will vary slightly from the steps presented here forWindows 2008 and SQL Server 2008.

Confirm NTFS File SystemBlackboard Learn will work only with the NTFS file system. It will not work correctly if theWindows file systemis FAT32. Follow the steps below to confirm that the disk is using the NTFS file system.

1. Double-click My Computer on your desktop.2. Right-click the drive where Blackboard Learn will be installed.3. Select Properties.4. The File system field must display NTFS. If it displays FAT32, consult the operating system

documentation for steps to convert the drive to NTFS.5. Repeat these steps on each application server, the database server, and the file system server.

ConfirmWindows Server 2003 Operating System PrerequisitesIf usingWindows Server 2003, the following requirements must bemet before beginning:

l Install theWindows 2003 Resource Kit and the IIS 6.0 Resource Kit on each application server.

Download theWindows Resource Kit and the IIS 6.0 Resource Kit fromMicrosoft athttp://download.microsoft.com.

l Install the SQL Server Client Tools on each application server.

The Client Tools allow the application servers to communicate with the database. Without the ClientTools, the Installer will fail. After installation, if the Client Tools are not available, the applicationserver will not be able to query the database or enter database transactions.

ConfirmWindows Server 2008 Operating System PrerequisitesThere is noWindows 2008 Resource Kit software package available fromMicrosoft for download at this time.The resource kit exists primarily as documentation for theWindows 2008 release.

There is no IIS 7 Resource Kit software package available fromMicrosoft for download at this time. Theresource kit exists primarily as documentation for theWindows 2008 release.

SQL Server Client Tools needs to be installed on each application server.


9.1 S

P6 BETA D

RAFT

http://download.microsoft.com/


Configure Windows Server 2008 IIS 7 Roles and FeaturesTo learnmore, see ConfiguringWindows Server 2008 IIS 7 Roles and Features.

Create a Domain UserCreate a domain user (for example, "blackboard") that will have access to the application server, the file server,and the database server. This user must be part of the Administrators group throughout the setup andinstallation. After this user is created, use it to log in to the servers.

When installing on one server, the application server, file system, and database are all run on onemachine.

When the installation is complete, youmay remove the domain user from the Administrators group as asecurity precaution. Remember to continue to use the domain user to run the Blackboard services.

Configure SQL Server Agent StartupThe SQL Server Agent must be running and set to Automatic startup for Blackboard Learn, where instance isthe name of the database instance (blank for a default instance).

1. Right-click Computer and selectManage.2. From the Server Manager, click Configuration and then click Services.3. Right-click SQL Server Agent (instance) and select Properties.4. From theStartup type drop-down list, select Automatic.5. Click OK.

Synchronize Server ClocksCheck the date and time on the system andmake sure it is accurate and that the time zone is set correctly. Ifinstalling on two servers, check that the time on the application server and database server match. Rememberthat the servers may be in a different time zone than the users. The server time zone should be the same as thetime zone used by themajority of users, instead of the physical location of the server. Blackboard Learn usesthe server date and time to control the availability of time-sensitivematerials. It is important that users have aclear expectation of whenmaterials will be available and when assignments are due.

Windows clients connected to a Domain can check their time offset using the following command, wheredomain_name is replaced with yourWindows domain: w32tm/monitor/domain:domain_name

Windows clients that are connected to a domain can force time synchronization using the following command:w32tm/resync

PortsBlackboard Learn requires TCP/IP ports to communicate. The following list details the required ports and theirdefault values. Make sure to configure server security and any firewalls to allow communication on the requiredports.

l Web server port (default value: 80): This port handles communication between users and the server.l Collaboration server TCP/IP port (default value: 8010): This port handles TCP communication for the

Collaboration server. By default, TCP communication connects users to the Collaboration server.l Collaboration server HTTP port (default value: 8011): This port handles HTTP communication for the

Collaboration server. HTTP is a backup if TCP communication fails.l SecureWeb server HTTPS port (default value:443): This port handles SSL over HTTP

communication between the users and the server. SSL capability is usually configured after the initialinstallation is complete.


9.1 S

P6 BETA D

RAFT


WARNING! Do not use a firewall to redirect ports. The internal port configured on the server must matchthe external port on the external firewall.

NetworkKeep inmind the following when connecting Blackboard Learn to the network:

l Do not use underscores in themachine name for the server or servers. Some versions of InternetExplorer block cookies if themachine name includes an underscore.

l Set up the DNS server to resolve server names.l Check with a network engineer to make sure that the network can handle the anticipated load after

Blackboard Learn is made available to users.l An SMTP server is available so that the Installer can connect to it.l An SMTP server has to remain available when the application is running in order to deliver email

notifications.

DatabaseKeep inmind the following when installing and configuringMicrosoft SQL Server:

l Install SQL Server at the drive level. For example, C:\SQL Server.l UseMixedMode Security Authentication.l Make sure SQL Server is installed using a local account.l Blackboard recommends using the default instance name except when installing SQL Server in a

failover cluster configuration. If the default instance name is not used, the instance namemust notinclude any underscores, spaces, or punctuation. Use only alphanumeric characters.

l If an instance other than the default is used, make sure that the instance is not case sensitive.l The SQL Server Client Tools must be installed on the application server. This is not necessary if

Blackboard Learn is installed on just one server.l Blackboard Learn supports SQL Server failover. To learnmore, see Set Up Database Clustering and

Storage.

Configuring Windows Server 2008 IIS 7 Roles and Features

Before You BeginWindows Server 2008 uses IIS 7. Before installation of Blackboard Learn 9.1, IIS 7 needs to be configured withspecific Role Services and other settings.

Blackboard recommends that you do not manually edit the%windir%\system32\inetsrv\config\applicationHost.config file to configure these options.This will result in errors that require a backup and restore of the last known good backup of the IIS 7configuration that was managed by the IIS.

If youmanually backed up the applicationHost.config file, restoring this manual backup and restartingIIS 7 will not fix errors generated by manually editing this file to configure IIS 7.

By default, IIS 7 will check every twominutes for changes to the configuration files and will automaticallycreate backups of them, maintaining a history of ten backups. Use the oldest of these backups to restore IIS 7to a working state.

%windir%\system32\inetsrv\appcmd.exe list backup%windir%\system32\inetsrv\appcmd.exerestore backup "CFGHISTORY_0000000021"


9.1 S

P6 BETA D

RAFT


Once the configuration has been restored and verified through web browser access, then use the appcmd utilityto configure the necessary features of IIS 7 as described in the section above.

If this approach does not solve the problem with IIS 7 generating errors, remove and then reinstall the IIS 7Role.

If you need to reinstall the IIS 7 Role, you can use the%BLACKBOARD%\tools\admin\WebsiteReinstall.bat command to re-establish the BlackboardWebsite within IIS.

How to Configure Windows Server 2008 IIS 7 Roles and Features1. Install the IIS 7 Role inWindows Server 2008 Server Manager and configure Role Services:

a. Click Start, select Administrative Tools, and then select Server Manager.b. Click Roles, and under theRoles Summary heading, click Add Roles.c. From the list of displayed roles, selectWeb Server (IIS).d. Click Next.

At aminimum, the following five (5) role services must be installed in addition to thedefault role services:

l Role Services > Web Server > Application Development > ISAPI Extensionsl Role Services > Web Server > Application Development > ISAPI Filtersl Role Services > Management Tools > IIS 6Management Compatibility > IIS

6Metabase Compatibilityl Role Services > Management Tools > IIS 6Management Compatibility > IIS

6WMI Compatibilityl Role Services > Management Tools > IIS 6Management Compatibility > IIS

6 Scripting Tools

To enhance performance, troubleshooting, and offer additional web serverconfiguration options, Blackboard recommends that the following role services also beinstalled:

l Role Services > Web Server > CommonHTTP Features > all five (5) roleservices enabled

l Role Services > Web Server > Application Development > all seven (7) roleservices enabled

l Role Services > Web Server > Security > all eight (8) role services enabledl Role Services > Management Tools > all three (3) role services enabledl Management Tools > IIS 6Management Capabilities > all four (4) role

services enabled.

Of the role services listed in this step, the following are will be of themost interest:

l Role Services > CommonHTTP Features > HTTP Redirection (to allow forHTTP redirection, in the event that the site is renamed)

l Role Services > Security > Windows Authentication (to allow for ActiveDirectory integrated authentication)

l Role Services > Security > IP and Domain Restrictions (to allow for greatercontrol of web server access)

l Role Services > Performance > Dynamic Content Compression (to allow forenhanced performance)


9.1 S

P6 BETA D

RAFT


e. SelectWindows Process Activation Service (.NET Environment), and then clickAdd Required Role services.

2. Disable the Default Web Site:a. Click Start, select Administrative Tools, and then select Server Manager.b. From the left menu, click the plus sign next toRoles to expand the tree.c. Click the plus sign next toWeb Server IIS, and then click Internet Information

Services (IIS) Manager.d. Under theConnections heading, click the plus sign next to the%HOSTNAME%, and

then click the plus sign next toSites.e. Right-click Default Web Site and from the drop-downmenu selectManage Web Site,

and then select Stop.3. Back up the current IIS 7 configuration and verify.

a. %windir%\system32\inetsrv\appcmd.exe add backup "Blackboard Pre-Change"

b. %windir%\system32\inetsrv\appcmd.exe list backup4. Modify the IIS 7 configuration to permit double escaping within URLs (applies to all sites).

a. %windir%\system32\inetsrv\appcmd set config/section:system.webServer/Security/requestFiltering -allowDoubleEscaping:True

5. Modify the IIS 7 configuration to allow upload files greater than 20MB in size, specified in bytes(applies to all sites).

a. %windir%\system32\inetsrv\appcmd set config -section:requestFiltering -requestLimits.maxAllowedContentLength:104857600

6. Back up the current IIS 7 configuration and verify.a. %windir%\system32\inetsrv\appcmd.exe add backup "Blackboard Post-

Change Backup"b. %windir%\system32\inetsrv\appcmd.exe list backup

7. Restart the IIS service.a. Click Start, select Administrative Tools, and then select Server Manager.b. From the left menu, click the plus sign next toConfiguration and then click Services.c. From the list of services, right-clickWorld Wide Web Publishing Service and select

Restart.

(Optional) Set Up Database Clustering and Storage for WindowsSetting up SQL Server Failover and setting up a separate storage device for the data files and log files areoptional steps. Many institutions, particularly Blackboard Learn - Basic Edition clients, will not need to set upSQL Server Failover or to set up the data files and log files on a separate storage device.

Setting Up SQL Server FailoverBlackboard Learn can be run using database clustering for redundancy. Database clustering instantly transfersdatabase requests to an identical server if the database server fails.

Blackboard Learn is designed to work with Microsoft SQL Server Failover clusters. SQL Server Failoverprovides added fault tolerance to the database by using another database in the cluster in the case of an errorthat causes the production database to fail.


9.1 S

P6 BETA D

RAFT


A SQLServer Failover cluster is based on the same design as aWindows cluster. A group of servers are joinedto provide continual service in the event of an outage or failure. When SQL Server is forced to shut down,another server steps in to handle requests.

The process for setting up aMicrosoft SQL Server failover cluster is done at the operating system anddatabase level before installing Blackboard Learn.

1. Set up theMicrosoft server cluster.2. Install SQL Server and configure the failover cluster.3. Install Blackboard Learn.

The following is a list of tips for setting up SQL Server failover.

l Use four public IP addresses: node 1, node 2, Windows cluster server, and virtual SQL server.l The local disk of each nodemust be attached to a separate SCSI controller. It should not use the

same one that is attached to the RAID system.l The RAID SCSI controller IDs of the two nodes must be different.l RAID SCSI BIOS must be set up to enable cluster (shared bus).l The names of the network cards cannot contain spaces or special characters.l Do not use the default instance name for installing SQL server on a virtual server. The instance name

must not include any underscores, spaces, or punctuation. Use only alphanumeric characters.l MSDTC servicemust be running before starting SQL server setup.

To learnmore about installing and configuring aMicrosoft SQL Server failover cluster, seeMicrosoft TechNetat http://www.microsoft.com/technet/. While Blackboard supports SQL Server failover with Blackboard Learn,Microsoft is the best resource for information about installing and configuring aMicrosoft SQL Server failovercluster.

Setting Up a Separate Storage Device for the Data Files and Log FilesThe Installer will prompt for the directory where the database data files and log files should be stored. ConsulttheMicrosoft SQL Server documentation for information about storing these files on a separate device. Keep inmind that the storage device should have a dedicated, high-bandwidth connection to the database server.

(Optional) Set Up File System Storage for WindowsSetting up file system storage on a separate storage device is an optional step for Blackboard Learn -Enterprise Edition clients.

Note: Blackboard Learn - Basic Edition clients must use the local default location ofc:\blackboard\content.

About File System StorageAll of the content files for Blackboard Learn, such as files uploaded to Courses and image files, are stored bydefault in the blackboard\content directory. If your school licenses content management, the ContentCollection has several content directories, each one dedicated to one of the top-level directories. For example,the \library directory stores all the files for the Library.

In a load-balanced configuration, this locationmust be accessible by all of the application servers. The locationcan be a share on one of the application servers or on the database server, or it can be a SAN (storage areanetwork) or NAS (network-attached storage) on a separate file server.

These instructions detail how to set up the blackboard\content directory on a separate file server. Thesamemethods can be repeated to set up the content management directories on a separate file server. The use


9.1 S

P6 BETA D

RAFT

http://www.microsoft.com/technet


of a separate storage device requires additional configuration of the Blackboard services to allow them to rununder the permission of a domain user.

How to Set Up a Shared File SystemFollow these steps to setup the blackboard\content directory on another server.

1. Log in to the file server as a domain user (for example, domain\blackboard) with administrativeprivileges. This is the user that runs theWeb/application server. That is, this must be the user thatlogs in to the application server and owns control of the Blackboard services. In this example, thedomain user is "blackboard."

2. Create a directory to store Blackboard Learn content files. For example, C:\bb_content.3. Right-click on the bb_content directory and select Properties.4. From theSharing tab, click Advanced Sharing.5. Select Share this folder.6. Click Permissions. ThePermissions for bb_contentwindow displays.7. Set Permissions so that the Administrators and the domain user who will be running the Blackboard

services, such as "blackboard," have full control. No other users should have access to thisdirectory.

8. After setting permissions, click theSecurity tab, and then click Edit.9. Set Security so that the Administrators and the domain user who will be running the Blackboard


10. Click OK.11. When prompted by the Installer for the location of the blackboard\content directory, type

\\FILESERVER\bb_content.12. If you are installing content management, the Installer will prompt for the location of the individual

Content Collection directories. When prompted, type the path to \\FILESERVER\bb_content\storage followed by a subdirectory name for each individual content managementdirectory. For example, the \users directory should be stored in \\FILESEVER\bb_content\storage\users. Alternatively, the Content Collection files can be stored on aseparate, dedicated, share directory.

Complete the Pre-Installation Checklist for Windows on One or TwoServersThe installation checklist below and the installation worksheet should be completed before installingBlackboard Learn on one or two servers. Completing both the checklist and the worksheet prior to installationwill help ensure a successful installation.

If Blackboard Learn will only be installed on one server, that machinemust pass the checklist for both theapplication server and the database server.

Blackboard BasicsReview the following list to make sure that Blackboard has provided everything necessary to begin installation.

l A valid Blackboard Learn license file is accessible from the application servers. To receive a licensefile, contact your Blackboard Client Representative.

l The Installer has been downloaded to the application servers. To receive instructions for downloadingthe Installer, contact your Blackboard Client Representative.


9.1 S

P6 BETA D

RAFT


l The Administrator has contact information for Blackboard Client Support and a login for Behind theBlackboard at https://behind.blackboard.com.

Application Server ChecklistReview the following list to make sure that the application server is prepared for installation.

l Themachine is connected to the network and powered on.l Themachinemeets theminimum hardware requirements.l A supported version of the operating system is installed on themachine.l The supported version of the JDK is installed on themachine.l The supported version of IIS is installed. If a remote content directory will be used, a domain user has

been created and IIS security configured appropriately.l Themachine is dedicated to Blackboard Learn and has no unnecessary software installed.l The Administrator has a plan for managing log files.l The Administrator has a plan for backing up the application file system.l The DNS (Domain Name Server) is set to resolve the server name. Note that the server name should

not contain underscore characters. Some versions of Microsoft Internet Explorer block cookies frommachines with an underscore in the name.

l If the database is running on a separate server, the SQL Server Client libraries are installed on theapplication server.

l Any firewalls are configured to allow access to Blackboard Learn ports. These ports are defined whenthe Installer is run. It is not possible to use a firewall to redirect to a different port. Blackboard Learnmust be available to users on the ports specified during the installation and not served through analternate port.

l The server clock is synchronized with the other servers used in Blackboard Learn configuration. If theserver clocks are not synchronized, theremay be differences between the displayed availability oftime-sensitive content and the actual availability of time-sensitive content.

l TheWindows file system is set to NTFS. Blackboard Learn will not work with a FAT32 file system.l The Installer can connect to the SMTP server.l Windows User Account Control is disabled in a 64-bit environment. For instructions, see

http://technet.microsoft.com/en-us/library/cc709691(WS.10).aspx.

Database Server ChecklistReview the following list to make sure that the database server is prepared for installation. Remember that ifBlackboard Learn will only be installed on one server, the database server and application server are configuredon onemachine.

l Themachine is connected to the network and powered on.l Themachinemeets theminimum hardware requirements.l A supported version of the operating system is installed on themachine.l A supported version of SQL Server was installed on the root directory with MixedMode Security

authentication using a local account.l If using a SQL Server failover cluster, make sure that the cluster is configured and SQL Server is

running properly.l The person installing Blackboard Learn knows the SQL Server Administrator password and what

instance of SQL Server will support Blackboard Learn.l Themachine is dedicated to Blackboard Learn and has no unnecessary software installed.


9.1 S

P6 BETA D

RAFT





l SQLServer is running. If SQL Server was installed just prior to Blackboard Learn, restart thedatabasemachine after installing SQL Server and prior to installing Blackboard Learn.

l The database administrator has a plan for backing up the database andmanaging database log files.l TheWindows file system is set to NTFS. Blackboard Learn will not work with a FAT32 file system.l If a database instance other than the default will be used, the instance name includes only

alphanumeric characters. Do not use punctuation or other characters, including underscores.l Verify that the SQL Server Database job agent can be successfully started up before installing or

updating the database. (See SQL Server Agent Automatic Startup.) If the job cannot be run, notify theDatabase Administrator so that it can be fixed before running the Installer.

Complete the Pre-Installation Worksheet for Windows on One or TwoServersThe installation worksheet helps identify all the information required by the Installer when installing on one ortwo servers. Filling out the worksheet prior to installation will help the installation process run smoothly.

The following information is needed by the Installer to complete the installation.

Blackboard Destination Directory: ___________________________________________

The path to a directory on the application server where Blackboard Learn will reside. The Installer will create adirectory called blackboard within this directory.

Setup Type: ___________________________________________

Select the Full Installation option to install Blackboard Learn on one or two servers. This option is also usedwhen installing Blackboard Learn on the database and first application server in a Load-Balanced configuration.

License File: ___________________________________________

The path to the current license file for this release and your institution. If a current License File is not available,contact your Blackboard Client Representative to request one. The License file determines which capabilities,such as the content management, are installed. The license file will be detected automatically if it is renamedbb-license.xml and placed in the same directory as the Installer.

Java Location: ___________________________________________

The path to the JDK.

Shared Content Directory: ___________________________________________

The path to the directory where the Blackboard Learn content files associated with Courses, images uploadedto the system, and all other files added to the system will be stored. The default location isc:\blackboard\content. The location can be a share on one of the application servers or on the databaseserver, or it can be a SAN (storage area network) or NAS (network-attached storage) on a separate file server.To learnmore about using a separate file server, see Set Up File System Storage forWindows.

Note: Blackboard Learn - Basic Edition clients must use the local default location.

Application Server Machine Name: ___________________________________________

The name of the application server. The Installer will automatically populate this value. The Installer must berun on the application server. To find themachine name of a server, follow the steps below.

1. Right-click My Computer and select Properties.2. Click the Network Identification tab.3. The full computer name and the domain name both appear. The full computer name is the

application server Machine Namewith the domain name appended(webservermachinename.domain).

Application Server Domain Name: ___________________________________________


9.1 S

P6 BETA D

RAFT


The name of the domain where theWeb server resides. The application server Machine Name and theapplication server Domain Name form the URL for Blackboard(http://webservermachinename.domain). Because these names form the URL, do not use anycharacters other than standard letters and numbers in the application server name or the domain name.Underscores and spaces will cause problems.

Application Server Port Number: ___________________________________________

The port that the application engine uses. The default value is 8009.

Web Server Port Number: ___________________________________________

The port that theWeb server will use for http connections with clients. The default value is 80.

Database Hostname: ___________________________________________

The domain name andmachine namewhere the SQL Server database that Blackboard Learn will use isinstalled. The databasemachine name can be found the sameway as theWeb server machine name. Wheninstalled on a one server configuration, the databasemachine name is the same as the application servermachine name. For this reason, the default value is themachine name of the local machine.

Database Instance: ___________________________________________

The name of the SQL Server instance that will run the Blackboard Learn database. This may be left blank ifBlackboard Learn will run on the default instance of SQL Server.

SQL System Database Administrator Password: _______________________________

The SQL System Database Administrator password associated with the "sa" login.

Blackboard Database User Password: ___________________________________________

A password for a SQL Server user that Blackboard Learn creates at install. This account is also used by theapplication to access the database.

Blackboard Database Report User Password: __________________________________

The password for the Database Report User. This is a SQL Server user that Blackboard Learn uses.

Database Identifier: ___________________________________________

Database identifiers must be unique within the database server. The database identifier is, by default,BBLEARN. If this parameter is left blank, it will default to BBLEARN. This option is not visible during anupgrade, and is typically used exclusively in amulti-tenancy environment. A multi-tenancy environment offersthe ability to host multiple Blackboard Learn instances on a single machine without the data being sharedbetween instances. Multi-tenancy environments are not standard. If you are upgrading your environment andwish to rename your database identifier, contact Blackboard Support for assistance.

Database Data Files Directory: ___________________________________________

The directory that will store Blackboard Learn database data files (.mdf). This directory will not store applicationdata or content. This directory must be on the database server.

Database Log Files Directory: ___________________________________________

The directory that will store Blackboard Learn database log files (.ldf). This directory will not store applicationorWeb logs. This directory must be on the database server.

Content Management Database Password: _______________________

This is the password for the database user that the Installer creates for the Content Collection databases. Thisvalue is required only if your school licenses content management.

Courses Directory: ___________________________________________

The path to the content management \courses directory. This directory will store all of the files under the\courses heading. This value is only required if your school licenses content management.

Institution Directory: ___________________________________________


9.1 S

P6 BETA D

RAFT


The path to the content management \institution directory. This directory will store all of the files underthe \institution heading. This value is only required if your school licenses content management.

Library Directory: ___________________________________________

The path to the content management \library directory. This directory will store all of the files under the/library heading. This value is required only if your school licenses content management.

Organization Directory: ___________________________________________

The path to the content management \orgs directory. This directory will store all of the files under the \orgsheading. This value is required only if your school licenses content management.

Users Directory: ___________________________________________

The path to the content management \users directory. This directory will store all of the files under the\users heading. This value is required only if your school licenses content management.

Collaboration Server Machine Name: _________________________________________

Themachine name that runs the Collaboration Server. It is possible to dual-purpose an existing application toalso serve as the Collaboration Server. Though not typically required, a separate server may be dedicated asthe Collaboration server exclusively. In one server and two server configurations, this machine name is thesame as the application server machine name.

Collaboration Server TCP/IP Port: ___________________________________________

TCP/IP is the preferred communicationmethod for the Collaboration server. The default port is 8010.

Collaboration Server HTTP Port: ___________________________________________

HTTP communication is used to connect users to the Collaboration server is TCP/IP communication isunavailable. The default port is 8011.

SMTP Server: ___________________________________________

The full hostname of the SMTP server that Blackboard Learn will use to send emails. For example:smtp.blackboard.com. The parameter bbconfig.email.bitbucket_address=email_addressmust be added and set in the bb-config.properties file to avoid system-generatedmessages, such asenrollment notifications and discussion board subscriptions from being sent to the administrator. The bit-bucketemail address should be set to a valid campus address that has no recipients, failure to use a valid address willresult in rejection by email servers.

Administrator Password: ___________________________________________

The Administrator account has full Administrator privileges. This account and the root_admin account are theonly two accounts that can log in until more users are created.

Integration User Password: ___________________________________________

The integration user is used only to facilitate Snapshot operations. This account cannot be used to log inthrough theGUI nor does it appear in any lists of users in the user interface. To change the password for thisaccount, on the Administrator Panel, underBuilding Blocks, click Integration Password.Root Administrator Password: ___________________________________________

The root_admin account has full administrative privileges including themanagement of Virtual Installationsthrough the Administrator Panel. When the root_admin account user views the Administrator Panel, theManage Virtual Installations link appears at the top of the panel. The root_admin can log in to any VirtualInstallation and access the Virtual Installationmanagement features from this link.

The root_admin account is created even if your license does not include the use of additional VirtualInstallations. The root_admin account can bemodified from the Edit Root Administrator Profile page.

Administrator Name: ___________________________________________

The name of the Administrator.

Administrator Email: ___________________________________________


9.1 S

P6 BETA D

RAFT


The email address of the Administrator.

Institution Name: ___________________________________________

The institution that will be using Blackboard Learn.

Institution Type: ___________________________________________

Choose one of the following options:l K-12l Higher Educationl Continuing Educationl Corporatel Professional Associationl Hobby

City: ___________________________________________

The state, province, or territory where the institution is located.

State: ___________________________________________


ZIP/Postal Code: ___________________________________________

The ZIP or Postal Code where the institution is located.

Country: ___________________________________________

The Country where the institution is located.

Install the Blackboard Learn Application Server and Database onWindowsThe Installer is launched from a command line prompt andmay be run using the command line interface or thegraphical interface. The Installer presents a series of questions about the system. Inmany cases, the Installerautomatically detects the required settings and provides default values.

Where to Find the InstallerTo request a current license file for this release and your institution and instructions for downloading theInstaller, contact your Blackboard Client Representative.

Before Running the InstallerMake sure that the systemmeets the supported software requirements and is properly configured beforerunning the Installer. To confirm that the system is ready for installation, see the Pre-Installation Checklist orthe Load-Balanced Pre-Installation Checklist.

The instructions below assume the following:

l You are currently logged in as the domain user, such as "blackboard."l The Installer is run on a two server system. The instructions reference the application server and the

database server. When installing on one server, thesemachines are the same.l The Installer is run using the graphical interface. The command line interface requires the same inputs

from the user. The only difference between the command line and theGUI interface is navigation. Thegraphical interface uses mouse-clicks instead of keystrokes to accept a value and continue. The


9.1 S

P6 BETA D

RAFT


command line places the default or anticipated value in brackets. Youmay either enter a new value orsimply press ENTER to select the value in brackets.

l The optional steps for installing content management: These steps are included for testing purposes.Blackboard recommends that content management be used only with Load-Balanced systems.

l The user is logged in as the "domain user."

How to Run the Installer1. Place both the Installer and the license file in a directory on the application server. The Installer will

automatically recognize the license file as long as it is named bb-license.xml and placed in thesame directory as the Installer. The following steps use C:\bb_installer as an example.

2. Double-click the Installer. Alternatively, open a command line prompt and navigate to the directorythat contains the Installer.

3. Run the following command to launch the Installer graphical interface:C:\bb_installer>java –jar installer_file

To launch the Installer command line interface, run the following command:C:\bb_installer>java –jar installer_file -text

Remember that the rest of these steps assume that the graphical interface is being used.

4. After reading the welcomemessage, press ENTER to continue.5. Provide the directory where Blackboard will be installed. To accept the default value of

C:\blackboard, click Next. Blackboard does not recommend changing this default.6. To select the type of installation, type 1for Full Installation and press ENTER.7. After reading the License Agreement, click Accept to continue the installation. To refuse the terms

of the agreement and close the Installer, click Do Not Accept.8. Provide the path and location of the license file. To accept the default value, click Next.To search

for the license file, click Browse and then click Next.9. Provide the location of the JDK. To accept the default value, click Next. To search for the JDK,

click Browse and then click Next.10. Provide the location of the Shared Content Directory, which is used to store the content files

associated with Courses, images uploaded to the system, and all other files added to the system.The location can be a share on one of the application servers or on the database server, or it can bea SAN (storage area network) or NAS (network-attached storage) on a separate file server. In aload-balanced configuration, this locationmust be accessible by all of the application servers. Tolearnmore about using a separate file server, see Set Up File System Storage forWindows. Toaccept the default value of c:\blackboard\content, press ENTER.


11. Provide the name of the application server. The Installer detects themachine name of the server itruns on and uses that to populate the default value.

12. Provide the domain that hosts the application server. The Installer detects this value and populatesthe default value.

13. Provide the port number for the application server. This is the port that the application uses forcommunication. The default value is 8009.

14. Provide the port number for theWeb server. This is the port that is used for http connections withusers. The default value is 80.

15. Click Next after completing all the fields on the page. The next page asks for information about thedatabase server. Remember that single server installations use the samemachine as both theapplication server and the database server.


9.1 S

P6 BETA D

RAFT


16. Provide the database server hostname. The default value is the current machine. This is the correctvalue for single server installations. If installing on two servers, enter a value for the separatedatabasemachine. Keep inmind that the hostname is represented by machine_name.domain_name.

17. Provide the database instance. In most cases, the default instance, which has no name, is used.18. After completing all of the fields on the page, click Next. The next page asks for the database

passwords.19. Provide the SQL Server database administrator password. This is the password associated with

the sa login. By default, the password for this account is blank.20. Provide the Blackboard database user password. This database login is used by the application to

access the database.21. Provide the Blackboard database report user password. This database login is used by the

application to access the reporting database.22. Optional step for Content Collection Users: Provide the content management database password.

This login is used by the application to access content management database.23. After completing all of the fields on the page, click Next. The next page asks where to store the

database data files and the database log files.24. Provide the location where the database data files (.mdf) will be stored. This directory must be on

the database server or on a storage device with a dedicated, high-bandwidth connection to thedatabase server. On a single server installation, the default value isC:\blackboard\mssql\data\. Click Next to accept the default or click Browse to provide anew value and then click Next.

25. Provide the location where the database log files (.ldf) will be stored. This directory must be on thedatabase server or on a storage device with a dedicated, high-bandwidth connection to thedatabase server. On a single server installation, the default value is C:\blackboard\mssql\data\.Click Next to accept the default or click Browse to provide a new value and then click Next.

26. After completing all of the fields on the page, click Next.27. Optional step for Content Collection Users: Provide the storage directories for content

management:

/courses - The default value is blackboard_directory\storage\courses.

/institution - The default value is blackboard_directory\storage\institution.

/library - The default value is blackboard_directory\storage\library.

/orgs - The default value is blackboard_directory\storage\orgs.

/users - The default value is blackboard_directory\storage\users.

28. After completing all of the fields on the page, click Next.29. Provide the Collaboration server hostname. In a one or two server environment, the default value is

the application server. In a load-balanced environment, select one of the existing applicationservers to also act as the Collaboration server. Though not typically required, a separate servermay be dedicated as the Collaboration server exclusively. To learnmore, see Set Up aCollaboration Server. The Collaboration server runs Virtual Classroom and chat sessions.

30. Provide the TCP port number for the Collaboration server. The Collaboration server uses TCP/IPas the preferred communicationmethod for performance reasons. The default port number is 8010.

31. Provide the HTTP port number for the Collaboration server. The Collaboration server uses HTTPas a backupmethod of communication if TCP/IP is not available. The default port number is 8011.

32. After completing all of the fields on the page, click Next.


9.1 S

P6 BETA D

RAFT


33. Provide the location of the SMTP server and click Next. The SMTP server is used to send outemail communications. Enter the hostname as machine_name.domain_name.

34. Provide the Blackboard Learn Administrator password. The Administrator account has fullprivileges.

35. Provide the Blackboard Integration password. The integration user is used only to facilitateSnapshot operations. This account cannot be used to log in through theGUI nor does it appear inany lists of users in the user interface. To change the password for this account, on theAdministrator Panel, underBuilding Blocks, click Integration Password.

36. Provide the Blackboard root administrator password. The root_admin account has fulladministrative privileges including themanagement of Virtual Installations through theAdministrator Panel. When the root_admin account user views the Administrator Panel, theManage Virtual Installations link appears at the top of the panel. The root_admin can log in to anyVirtual Installation and access the Virtual Installationmanagement features from this link. While itis necessary to enter a password for this account, it is very rare that a system with VirtualInstallations will be run on one server or two servers.

37. After completing all of the fields on the page, click Next.38. Provide the following information about the administrator and the institution:

l Name and email address of the administratorl Name of Institutionl Type of Institution - The valuemust be one of the following: K-12, Higher Education,

Continuing Education, Corporate, Professional Association, or Hobbyl City, State, Country, and ZIP Code of the institution's address

39. After completing all of the fields on the page, click Next.40. Select the Server Type. This is information is used for better management of centralized services.

Options include: Production, Staging, Test, andDevelopment. Properly categorize each serverwhen running the installer.

41. Click Next.42. Click Next again to install the software. If the Installer was launched from the command line, do not

close the command line window or any of the other windows that pop-up during the installation.

If the Installer failed, check the Installer log and see Troubleshooting to diagnose and fix the problem.

Next StepsMake sure to remove the domain user from the Administrators group on each server. This is a security steprecommended by Microsoft that prevents the domain user, which is used to run services, from acting as anAdministrator.

If a separate storage device has been configured with a UNC path (\\server\share),make sure configurethe services with proper permissions.

Install on Windows in a Load-Balanced ConfigurationThe following section explains the required hardware, software, and necessary steps to properly installBlackboard Learn onWindows in a load-balanced configuration. It also includes a section on proper review ofthe installation and next steps in administration of the system.

1. Set Up the Hardware and Software2. (Optional) Set Up Database Clustering and Storage3. (Optional) Set Up File System Storage


9.1 S

P6 BETA D

RAFT


4. Complete the Pre-Installation Checklist5. Complete the Pre-InstallationWorksheet6. Install the Blackboard Learn Application Server and Database7. Install the Blackboard Learn Software on Additional Application Servers8. (Optional) Set Up a Clustered Tomcat Environment9. (Optional) Set Up Collaboration Server10. Set Up the Blackboard Services on Each Application Server11. Set Up the Hardware Load Balancer

Set Up the Hardware and Software on Windows in a Load-BalancedConfigurationA load-balanced configuration requires that the first application server and database server be installed usingthe two server configurationmodel. After that, the Installer can be run again on each additional applicationserver to install only those components. Each additional Web/application server must alsomeet the requiredprerequisites.

Make sure that the hardware, software, and network are prepared before beginning to configure and installBlackboard Learn in a load-balanced environment.




Download and install the JDK on each application server.


Collaboration ServerSelect one of the existing application servers to also act as the Collaboration server. Alternatively, a separateserver may be dedicated as the Collaboration server. To learnmore, see Set Up a Collaboration Server. TheCollaboration server may not be spread across multiple application servers because all users participating in aCollaboration sessionmust share the same resources. A single server must be configured to run theCollaboration server. This server must handle Collaboration sessions and performance will be unaffected byother requests. The application servers are configured to connect users to one server that handles all theCollaboration sessions.

The Collaboration server must be configured to use the domain account in a load balanced environment. Do notconnect the Collaboration server to the load-balancer.


9.1 S

P6 BETA D

RAFT





Dedicated File System ServerSet aside one server as a dedicated file system server. The content files must be centralized so that all files areavailable to users regardless of the application server handling the connection. The application servers areconfigured to find the content files in a directory on the file system server.

Set JAVA_HOMEThe correct version of the JDK must be installed on the application server and the JAVA_HOME environmentvariable must be set. The JDK installer first installs the JDK, then the Java Runtime Environment (JRE).Ensure that these are installed to different locations and the JRE installer is not allowed to overwrite portions ofthe JDK.

IMPORTANT! Make sure that the path to the JDK does not include any spaces. For example, do not useC:\Program Files\Java\jdk1.6.0_18. Instead, use C:\Java\jdk1.6.0_18.

Follow these steps to set the JAVA_HOME environment variable:

1. Make sure that the correct version of the JDK is installed on the application server.2. Right-click Computer and select Properties.3. Click Advanced System Properties.4. Click Environment Variables.5. In the system variables list, find JAVA_HOME and click Edit. If JAVA_HOME does not exist in the

system variables list, click New. A pop-up window will appear. TheVariable name should readJAVA_HOME.

6. Enter the full path to the JDK in theVariable value field. For example, C:\Java\jdk1.6.0_18.7. Click OK.

Note: Click paths forWindows 2003 and SQL 2005 will vary slightly from the steps presented here forWindows 2008 and SQL Server 2008.

Confirm NTFS File SystemBlackboard Learn will work only with the NTFS file system. It will not work correctly if theWindows file systemis FAT32. Follow the steps below to confirm that the disk is using the NTFS file system.

1. Double-click My Computer.2. Right-click on the disk where Blackboard Learn will be installed.3. Select Properties.4. The File System field should show NTFS. If it shows FAT32, consult the operating system

documentation for instructions on converting the disk to a NTFS file system.5. Repeat these steps on each application server, the database server, and the file system server.

ConfirmWindows Server 2003 PrerequisitesIf usingWindows Server 2003, the following requirements must bemet before beginning:

l Install theWindows 2003 Resource Kit and the IIS 6.0 Resource Kit on each application server.

Download theWindows Resource Kit and the IIS 6.0 Resource Kit fromMicrosoft athttp://download.microsoft.com.


9.1 S

P6 BETA D

RAFT

http://download.microsoft.com/


l Install the SQL Server Client Tools on each application server.

The Client Tools allow the application servers to communicate with the database. Without the ClientTools, the Installer will fail. After installation, if the Client Tools are not available, the applicationserver will not be able to query the database or enter database transactions.

ConfirmWindows Server 2008 Operating System PrerequisitesThere is noWindows 2008 Resource Kit software package available fromMicrosoft for download at this time.The resource kit exists primarily as documentation for theWindows 2008 release.

There is no IIS 7 Resource Kit software package available fromMicrosoft for download at this time. Theresource kit exists primarily as documentation for theWindows 2008 release.

SQL Server Client Tools needs to be installed on each application server.

Configure Windows Server 2008 IIS 7 Roles and FeaturesTo learnmore, see ConfiguringWindows Server 2008 IIS 7 Roles and Features.

Create a Domain UserCreate a domain user (for example, “blackboard”) that will have access to the application servers, the fileserver, and the database server. This user must be part of the Administrators group throughout the setup andinstallation. After this user is created, use it to log in to the servers.

Add the Domain User to the IIS_WPGGroupThe domain user created in the steps abovemust be added to the IIS_IUSRS Group, where domain_name isreplaced with yourWindows domain: w32tm/monitor/domain:domain_name. If this association is notcreated, the website will not display.

1. Log in as the domain user.2. Right-click Computer and selectManage.3. From the Server Manager, click Configuration, and then click the plus sign next to Local Users

and Groups to expand the folders.4. Click Groups.5. Right-click on IIS_IUSRS.6. Select Add to Group from the drop-down list.7. Click Add.8. Enter the domain user "blackboard".9. Click OK.10. If asked to enter the username and password for that account, do so, and then click OK.

Set Up IIS SecurityThe domain user created in the steps abovemust be added to IIS security. Follow these steps to configure IISon each application server.

1. Log in as the domain user (for example, domain\blackboard) on the first application server.2. Right-click Computer and selectManage.3. From the Server Manager, click Roles, clickWeb Server (IIS), then click Internet Information

Services (IIS) Manager.


9.1 S

P6 BETA D

RAFT


4. Stop the Default Web Site by expandingSites, right-clicking onDefault Web Site, selectingManage Web Site, and then selectingStop.

5. Configure Directory Security by clicking the Features View button at the bottom of the page andthen double-clickingAuthentication.

6. Right-click onAnonymous Authentication and select Edit. IUSR should appear in the specificuser field.

7. Configure the Application Pool by clickingApplication Pools.8. Right-click DefaultAppPool and select Advanced Settings.9. Under the Process Model heading, in the Identity /NetworkService cell, click the ... (ellipses)

button.10. Select Custom account, then click Set.11. Enter the domain user name and password, and then click OK.12. Restart IIS so that the changes will take effect.13. Repeat these steps for each application server.

Configure SQL Server Agent Automatic StartupThe SQL Server Agent must be running and set to Automatic startup for Blackboard Learn where%INSTANCE% is the name of the database instance (blank for a default instance).

1. Right-click Computer and selectManage.2. From the Server Manager, click Configuration and then click Services.3. Right-click SQL Server Agent (instance) and select Properties.4. From theStartup type drop-down list, select Automatic.5. Click OK.

Synchronize Server ClocksCheck the date and time on the system andmake sure it is accurate and that the time zone is set correctly.Check that the time on the application server and database server match. Remember that the servers may bein a different time zone than users. Blackboard Learn uses the server date and time to control the availability oftime-sensitivematerials. It is important that users have a clear expectation of whenmaterials will be availableand when assignments are due.

Windows clients connected to a Domain can check their time offset using the following commandwheredomain_name is replaced with yourWindows domain: w32tm/monitor/domain:domain_name

Windows clients that are connected to a domain can force time synchronization using the following command:w32tm/resync

PortsBlackboard Learn requires ports to communicate. The list below details the required ports and their defaultvalues. Make sure to configure server security and any firewalls to allow communication on the required ports.All application servers must use the same port settings.



Collaboration server. HTTP is a backup if TCP communication fails.


9.1 S

P6 BETA D

RAFT


l SecureWeb server HTTPS port (default value:443): This port handles SSL over HTTPcommunication between the users and the server. SSL capability is usually configured after the initialinstallation is complete.



l Do not use underscores in themachine name for the server or servers.l Set up the DNS server to resolve the hardware load-balancer. The hardware load-balancer will then

direct traffic to the application servers. Set up a separate DNS entry for the dedicated Collaborationserver.

l Check with a network engineer to make sure that the network can handle the anticipated load afterBlackboard Learn is made available to users.

l An SMTP server is available so that the Installer can connect to it.l An SMTP server has to remain available when the application is running in order to deliver email

notifications.

DatabaseKeep inmind the following when installing and configuringMicrosoft SQL Server:

l Install SQL Server at the drive level, for example, C:\SQL Server.l UseMixedMode Security Authentication.l Make sure SQL Server is installed using a local account.l Blackboard recommends using the default instance name. If the default instance name is not used,

the instance namemust not include any underscores, spaces, or punctuation. Use only alphanumericcharacters.

l If an instance other than the default is used, make sure that the instance is not case sensitive.l The default password for the 'sa' account is a blank value.l The SQL Server Client Tools must be installed on each application server.l Blackboard Learn supports SQL Server failover. To learnmore, see Set Up Database Clustering and

Separate Storage.

Configuring Windows Server 2008 IIS 7 Roles and Features

Before You BeginWindows Server 2008 uses IIS 7. Before installation of Blackboard Learn 9.1, IIS 7 needs to be configured withspecific Role Services and other settings.

Blackboard recommends that you do not manually edit the%windir%\system32\inetsrv\config\applicationHost.config file to configure these options.This will result in errors that require a backup and restore of the last known good backup of the IIS 7configuration that was managed by the IIS.

If youmanually backed up the applicationHost.config file, restoring this manual backup and restartingIIS 7 will not fix errors generated by manually editing this file to configure IIS 7.


9.1 S

P6 BETA D

RAFT


By default, IIS 7 will check every twominutes for changes to the configuration files and will automaticallycreate backups of them, maintaining a history of ten backups. Use the oldest of these backups to restore IIS 7to a working state.

%windir%\system32\inetsrv\appcmd.exe list backup%windir%\system32\inetsrv\appcmd.exerestore backup "CFGHISTORY_0000000021"

Once the configuration has been restored and verified through web browser access, then use the appcmd utilityto configure the necessary features of IIS 7 as described in the section above.

If this approach does not solve the problem with IIS 7 generating errors, remove and then reinstall the IIS 7Role.

If you need to reinstall the IIS 7 Role, you can use the%BLACKBOARD%\tools\admin\WebsiteReinstall.bat command to re-establish the BlackboardWebsite within IIS.

How to Configure Windows Server 2008 IIS 7 Roles and Features1. Install the IIS 7 Role inWindows Server 2008 Server Manager and configure Role Services:

a. Click Start, select Administrative Tools, and then select Server Manager.b. Click Roles, and under theRoles Summary heading, click Add Roles.c. From the list of displayed roles, selectWeb Server (IIS).d. Click Next.

At aminimum, the following five (5) role services must be installed in addition to thedefault role services:

l Role Services > Web Server > Application Development > ISAPI Extensionsl Role Services > Web Server > Application Development > ISAPI Filtersl Role Services > Management Tools > IIS 6Management Compatibility > IIS

6Metabase Compatibilityl Role Services > Management Tools > IIS 6Management Compatibility > IIS

6WMI Compatibilityl Role Services > Management Tools > IIS 6Management Compatibility > IIS

6 Scripting Tools

To enhance performance, troubleshooting, and offer additional web serverconfiguration options, Blackboard recommends that the following role services also beinstalled:

l Role Services > Web Server > CommonHTTP Features > all five (5) roleservices enabled

l Role Services > Web Server > Application Development > all seven (7) roleservices enabled

l Role Services > Web Server > Security > all eight (8) role services enabledl Role Services > Management Tools > all three (3) role services enabledl Management Tools > IIS 6Management Capabilities > all four (4) role

services enabled.

Of the role services listed in this step, the following are will be of themost interest:

l Role Services > CommonHTTP Features > HTTP Redirection (to allow forHTTP redirection, in the event that the site is renamed)


9.1 S

P6 BETA D

RAFT


l Role Services > Security > Windows Authentication (to allow for ActiveDirectory integrated authentication)

l Role Services > Security > IP and Domain Restrictions (to allow for greatercontrol of web server access)

l Role Services > Performance > Dynamic Content Compression (to allow forenhanced performance)

e. SelectWindows Process Activation Service (.NET Environment), and then clickAdd Required Role services.

2. Disable the Default Web Site:a. Click Start, select Administrative Tools, and then select Server Manager.b. From the left menu, click the plus sign next toRoles to expand the tree.c. Click the plus sign next toWeb Server IIS, and then click Internet Information

Services (IIS) Manager.d. Under theConnections heading, click the plus sign next to the%HOSTNAME%, and

then click the plus sign next toSites.e. Right-click Default Web Site and from the drop-downmenu selectManage Web Site,

and then select Stop.3. Back up the current IIS 7 configuration and verify.

a. %windir%\system32\inetsrv\appcmd.exe add backup "Blackboard Pre-Change"

b. %windir%\system32\inetsrv\appcmd.exe list backup4. Modify the IIS 7 configuration to permit double escaping within URLs (applies to all sites).

a. %windir%\system32\inetsrv\appcmd set config/section:system.webServer/Security/requestFiltering -allowDoubleEscaping:True

5. Modify the IIS 7 configuration to allow upload files greater than 20MB in size, specified in bytes(applies to all sites).

a. %windir%\system32\inetsrv\appcmd set config -section:requestFiltering -requestLimits.maxAllowedContentLength:104857600

6. Back up the current IIS 7 configuration and verify.a. %windir%\system32\inetsrv\appcmd.exe add backup "Blackboard Post-

Change Backup"b. %windir%\system32\inetsrv\appcmd.exe list backup

7. Restart the IIS service.a. Click Start, select Administrative Tools, and then select Server Manager.b. From the left menu, click the plus sign next toConfiguration and then click Services.c. From the list of services, right-clickWorld Wide Web Publishing Service and select

Restart.

(Optional) Set Up Database Clustering and Storage for WindowsSetting up SQL Server Failover and setting up a separate storage device for the data files and log files areoptional steps. Many institutions, particularly Blackboard Learn - Basic Edition clients, will not need to set upSQL Server Failover or to set up the data files and log files on a separate storage device.


9.1 S

P6 BETA D

RAFT


Setting Up SQL Server FailoverBlackboard Learn can be run using database clustering for redundancy. Database clustering instantly transfersdatabase requests to an identical server if the database server fails.

Blackboard Learn is designed to work with Microsoft SQL Server Failover clusters. SQL Server Failoverprovides added fault tolerance to the database by using another database in the cluster in the case of an errorthat causes the production database to fail.

A SQL Server Failover cluster is based on the same design as aWindows cluster. A group of servers are joinedto provide continual service in the event of an outage or failure. When SQL Server is forced to shut down,another server steps in to handle requests.

The process for setting up aMicrosoft SQL Server failover cluster is done at the operating system anddatabase level before installing Blackboard Learn.

1. Set up theMicrosoft server cluster.2. Install SQL Server and configure the failover cluster.3. Install Blackboard Learn.

The following is a list of tips for setting up SQL Server failover.

l Use four public IP addresses: node 1, node 2, Windows cluster server, and virtual SQL server.l The local disk of each nodemust be attached to a separate SCSI controller. It should not use the

same one that is attached to the RAID system.l The RAID SCSI controller IDs of the two nodes must be different.l RAID SCSI BIOS must be set up to enable cluster (shared bus).l The names of the network cards cannot contain spaces or special characters.l Do not use the default instance name for installing SQL server on a virtual server. The instance name

must not include any underscores, spaces, or punctuation. Use only alphanumeric characters.l MSDTC servicemust be running before starting SQL server setup.

To learnmore about installing and configuring aMicrosoft SQL Server failover cluster, seeMicrosoft TechNetat http://www.microsoft.com/technet/. While Blackboard supports SQL Server failover with Blackboard Learn,Microsoft is the best resource for information about installing and configuring aMicrosoft SQL Server failovercluster.

Setting Up a Separate Storage Device for the Data Files and Log FilesThe Installer will prompt for the directory where the database data files and log files should be stored. ConsulttheMicrosoft SQL Server documentation for information about storing these files on a separate device. Keep inmind that the storage device should have a dedicated, high-bandwidth connection to the database server.

(Optional) Set Up File System Storage for WindowsSetting up file system storage on a separate storage device is an optional step for Blackboard Learn -Enterprise Edition clients.

Note: Blackboard Learn - Basic Edition clients must use the local default location ofc:\blackboard\content.

About File System StorageAll of the content files for Blackboard Learn, such as files uploaded to Courses and image files, are stored bydefault in the blackboard\content directory. If your school licenses content management, the Content


9.1 S

P6 BETA D

RAFT

http://www.microsoft.com/technet


Collection has several content directories, each one dedicated to one of the top-level directories. For example,the \library directory stores all the files for the Library.


These instructions detail how to set up the blackboard\content directory on a separate file server. Thesamemethods can be repeated to set up the content management directories on a separate file server. The useof a separate storage device requires additional configuration of the Blackboard services to allow them to rununder the permission of a domain user.

How to Set Up a Shared File SystemFollow these steps to setup the blackboard\content directory on another server.

1. Log in to the file server as a domain user (for example, domain\blackboard) with administrativeprivileges. This is the user that runs theWeb/application server. That is, this must be the user thatlogs in to the application server and owns control of the Blackboard services. In this example, thedomain user is "blackboard."

2. Create a directory to store Blackboard Learn content files. For example, C:\bb_content.3. Right-click on the bb_content directory and select Properties.4. From theSharing tab, click Advanced Sharing.5. Select Share this folder.6. Click Permissions. ThePermissions for bb_contentwindow displays.7. Set Permissions so that the Administrators and the domain user who will be running the Blackboard


8. After setting permissions, click theSecurity tab, and then click Edit.9. Set Security so that the Administrators and the domain user who will be running the Blackboard


10. Click OK.11. When prompted by the Installer for the location of the blackboard\content directory, type

\\FILESERVER\bb_content.12. If you are installing content management, the Installer will prompt for the location of the individual

Content Collection directories. When prompted, type the path to \\FILESERVER\bb_content\storage followed by a subdirectory name for each individual content managementdirectory. For example, the \users directory should be stored in \\FILESEVER\bb_content\storage\users. Alternatively, the Content Collection files can be stored on aseparate, dedicated, share directory.

Complete the Pre-Installation Checklist for Windows in a Load-BalancedConfigurationThe installation checklist below and the installation worksheet should be completed before installingBlackboard Learn in a load-balanced configuration. Completing both the checklist and the worksheet prior toinstallation will help ensure a successful installation.



9.1 S

P6 BETA D

RAFT


l A valid Blackboard Learn license file is accessible from the application servers. To receive a licensefile, contact your Blackboard Client Representative.


l The Administrator has contact information for Blackboard Technical Support and a login for Behindthe Blackboard at https://behind.blackboard.com.

Application Servers ChecklistReview the following list to make sure that each application server is prepared for installation.

l Themachine is connected to the network and powered on.l Themachinemeets theminimum hardware requirements.l A supported version of the operating system is installed on themachine.l The supported version of the JDK is installed on themachine.l The supported version of IIS is installed. If a remote content directory will be used, a domain user has

been created and IIS security configured appropriately.l Themachine is dedicated to Blackboard Learn and has no unnecessary software installed.l The Administrator has a plan for managing log files.l The Administrator has a plan for backing up the application file system.l The DNS (Domain Name Server) is set to resolve the name of the load balancer. Note that the load

balancer name should not contain underscore characters. Some versions of Microsoft InternetExplorer block cookies frommachines with an underscore in the name.

l Blackboard Learn application servers must be part of theWindows domain. An alternate scenarioinvolves the DNS servicemay be enabled on Blackboard Learn application server with a forwardlookup record created for it on the application server.

l If the database is running on a separate server, the SQL Server Client libraries are installed on theapplication server.

l Blackboard Learn connects to the SQL Server instance over TCP/IP. The SQL Server network utilitymust be used to enable the TCP/IP protocol before installation. Blackboard recommends use of theNamed Pipes protocol.



l TheWindows file system is set to NTFS. Blackboard Learn will not work with a FAT32 file system.l The Installer can connect to the SMTP server.l If using a clustered Tomcat environment, the Server Groups and Ports have been configured. This is

especially important when upgrading an existing clustered Tomcat environment.l Windows User Account Control is disabled in a 64-bit environment. For instructions, see

http://technet.microsoft.com/en-us/library/cc709691(WS.10).aspx.

Database Server ChecklistReview the following list to make sure that the database server is prepared for installation:


9.1 S

P6 BETA D

RAFT





l Themachine is connected to the network and powered on.l Themachinemeets theminimum hardware requirements.l A supported version of the operating system is installed on themachine.l A supported version of SQL Server was installed on the root directory with MixedMode Security

authentication using a local account.l If using a SQL Server failover cluster, the cluster is configured and SQL Server is running properly.l The person installing Blackboard Learn knows the SQL Server Administrator password and what

instance of SQL Server will support Blackboard Learn.l Themachine is dedicated to Blackboard Learn and has no unnecessary software installed.l SQLServer is running. If SQL Server was installed just prior to Blackboard Learn, restart the

databasemachine after installing SQL Server and prior to installing Blackboard Learn.l The database administrator has a plan for backing up the database andmanaging database log files.l The file system is set to NTFS. Blackboard Learn will not work with a FAT32 file system.l If a database instance other than the default will be used, the instance name includes only

alphanumeric characters. Do not use punctuation or other characters, including underscores.l Verify that the SQL Server Database job agent can be successfully started up before installing or

updating the database. To learnmore, see SQL Server Agent Automatic Startup. If the job cannot berun, notify the Database Administrator so that it can be fixed before running the Installer.

(Optional) File System Server ChecklistIf file system storage will be set up on a separate storage device, review the following list to make sure that thefile system server is prepared for installation.

l The Administrator has a plan for backing up the application file system.l A directory to store the Blackboard content is configured and shared. Another directory for content

management content (available only if your school licenses content management) is configured andshared, if desired.

l The domain user that will run the application services has full access to the shared directories.

(Optional) Collaboration Server ChecklistIf the Collaboration server will be set up on a Separate Device, make sure that the Collaboration server uses adifferent DNS name than that of the application servers.

Complete the Pre-Installation Worksheet for Windows in a Load-BalancedConfigurationNote: Blackboard Learn - Basic Edition clients must use the local default location.


The name of the application server. The Installer will automatically populate this value. The Installer must berun on the application server. Complete the following steps to find themachine name of a server.

1. Right-click My Computer and select Properties from the context menu.2. Click the Network Identification tab.3. The full computer name and the domain name both appear. The full computer name is the

application server Machine Namewith the domain name appended(webservermachinename.domain).



9.1 S

P6 BETA D

RAFT

#SQL_Server_Agent_Automatic_Startup






The name of the domain where theWeb server resides. The application server Machine Name and theapplication server Domain Name form the URL for Blackboard (http://webservermachinename.domain).Because these names form the URL, do not use any characters other than standard letters and numbers in theapplication server name or the domain name. Underscores and spaces will cause problems.


The port that the application engine uses. The default value is 8009.




The domain name andmachine namewhere the SQL Server database that Blackboard Learn will use isinstalled. The databasemachine name can be found the sameway as theWeb server machine name.

Database Instance: ___________________________________________

The name of the SQL Server instance that will run Blackboard Learn database. This may be left blank ifBlackboard Learn will run on the default instance of SQL Server.

SQL System Database Administrator Password: _______________________________

The SQL System Database Administrator password associated with the "sa" login.

Blackboard Database User Password: ________________________________________

A password for a SQL Server user that Blackboard Learn creates at install. This account is also used by theapplication to access the database.


The password for the Database Report User. This is a SQL Server user that Blackboard Learn uses.


Database identifiers must be unique within the database server. The database identifier is, by default,BBLEARN. If this parameter is left blank, it will default to BBLEARN. This option is not visible during anupgrade, and is typically used exclusively in amulti-tenancy environment. A multi-tenancy environment offersthe ability to host multiple Blackboard Learn instances on a single machine without the data being sharedbetween instances. Multi-tenancy environments are not standard. If you are upgrading your environment andwish to rename your database identifier, contact Blackboard Support for assistance.

Database Data Files Directory: ___________________________________________

The directory that will store Blackboard Learn database log files (.mdf). This directory will not store applicationdata or content. This directory must be on the database server.

Database Log Files Directory: ___________________________________________

The directory that will store Blackboard Learn database log files (.ldf). This directory will not store applicationorWeb logs. This directory must be on the database server.


The password for the database user that the Installer creates for the content management databases. Thisvalue is required only if your school licenses content management.


Enter the path to the content management /courses directory. This directory will store all of the files under the/courses heading. This value is required only if your school licenses content management.


The path to the content management /institution directory. This directory will store all of the files underthe /institution heading. This value is required only if your school licenses content management.



9.1 S

P6 BETA D

RAFT


The path to the content management /library directory. This directory will store all of the files under the/library heading. This value is required only if your school licenses content management.

Orgs Directory: ___________________________________________

The path to the content management /orgs directory. This directory will store all of the files under the /orgs

heading. This value is required only if your school licenses content management.

Users Directory: ___________________________________________

The path to the content management /users directory. This directory will store all of the files under the/users heading. This value is required only if your school licenses content management.


Themachine name that runs the Collaboration Server. It is possible to dual-purpose an existing application toalso serve as the Collaboration Server. Though not typically required, a separate server may be dedicated asthe Collaboration server exclusively. In Load-Balanced configurations, it is important to direct all CollaborationTool traffic to one server to maintain session integrity across users.


TCP/IP is the preferred communicationmethod for the Collaboration Server. The default port is 8010.


HTTP communication is used to connect users to the Collaboration Server is TCP/IP communication isunavailable. The default port is 8011.

SMTP Server: ___________________________________________

The full hostname of the SMTP server that Blackboard Learn will use to send email. For example:smtp.blackboard.com. The parameter bbconfig.email.bitbucket_address=email_addressmust be added and set in the bb-config.properties file to avoid system-generatedmessages, such asenrollment notifications and discussion board subscriptions from being sent to the administrator. The bit-bucketemail address should be set to a valid campus address that has no recipients, failure to use a valid address willresult in rejection by email servers.




The integration user is used only to facilitate Snapshot operations. This account cannot be used to log inthrough theGUI nor does it appear in any lists of users in the user interface. To change the password for thisaccount, on the Administrator Panel, underBuilding Blocks, click Integration PasswordRoot Administrator Password: ___________________________________________









9.1 S

P6 BETA D

RAFT




Choose one of the following options:

l K-12l Higher Educationl Continuing Educationl Corporatel Professional Associationl Hobby

City: ___________________________________________


State: ___________________________________________


ZIP/Postal Code: ___________________________________________


Country: ___________________________________________


Install the Blackboard Learn Application Server and Database onWindowsThe Installer is launched from a command line prompt andmay be run using the command line interface or thegraphical interface. The Installer presents a series of questions about the system. Inmany cases, the Installerautomatically detects the required settings and provides default values.


Before Running the InstallerMake sure that the systemmeets the supported software requirements and is properly configured beforerunning the Installer. To confirm that the system is ready for installation, see the Pre-Installation Checklist orthe Load-Balanced Pre-Installation Checklist.


l You are currently logged in as the domain user, such as "blackboard."l The Installer is run on a two server system. The instructions reference the application server and the

database server. When installing on one server, thesemachines are the same.l The Installer is run using the graphical interface. The command line interface requires the same inputs

from the user. The only difference between the command line and theGUI interface is navigation. Thegraphical interface uses mouse-clicks instead of keystrokes to accept a value and continue. Thecommand line places the default or anticipated value in brackets. Youmay either enter a new value orsimply press ENTER to select the value in brackets.


9.1 S

P6 BETA D

RAFT



l The user is logged in as the "domain user."

How to Run the Installer1. Place both the Installer and the license file in a directory on the application server. The Installer will

automatically recognize the license file as long as it is named bb-license.xml and placed in thesame directory as the Installer. The following steps use C:\bb_installer as an example.

2. Double-click the Installer. Alternatively, open a command line prompt and navigate to the directorythat contains the Installer.

3. Run the following command to launch the Installer graphical interface:C:\bb_installer>java –jar installer_file

To launch the Installer command line interface, run the following command:C:\bb_installer>java –jar installer_file -text


4. After reading the welcomemessage, press ENTER to continue.5. Provide the directory where Blackboard will be installed. To accept the default value of

C:\blackboard, click Next. Blackboard does not recommend changing this default.6. To select the type of installation, type 1for Full Installation and press ENTER.7. After reading the License Agreement, click Accept to continue the installation. To refuse the terms

of the agreement and close the Installer, click Do Not Accept.8. Provide the path and location of the license file. To accept the default value, click Next.To search

for the license file, click Browse and then click Next.9. Provide the location of the JDK. To accept the default value, click Next. To search for the JDK,

click Browse and then click Next.10. Provide the location of the Shared Content Directory, which is used to store the content files

associated with Courses, images uploaded to the system, and all other files added to the system.The location can be a share on one of the application servers or on the database server, or it can bea SAN (storage area network) or NAS (network-attached storage) on a separate file server. In aload-balanced configuration, this locationmust be accessible by all of the application servers. Tolearnmore about using a separate file server, see Set Up File System Storage forWindows. Toaccept the default value of c:\blackboard\content, press ENTER.


11. Provide the name of the application server. The Installer detects themachine name of the server itruns on and uses that to populate the default value.

12. Provide the domain that hosts the application server. The Installer detects this value and populatesthe default value.

13. Provide the port number for the application server. This is the port that the application uses forcommunication. The default value is 8009.

14. Provide the port number for theWeb server. This is the port that is used for http connections withusers. The default value is 80.

15. Click Next after completing all the fields on the page. The next page asks for information about thedatabase server. Remember that single server installations use the samemachine as both theapplication server and the database server.

16. Provide the database server hostname. The default value is the current machine. This is the correctvalue for single server installations. If installing on two servers, enter a value for the separate


9.1 S

P6 BETA D

RAFT


databasemachine. Keep inmind that the hostname is represented by machine_name.domain_name.

17. Provide the database instance. In most cases, the default instance, which has no name, is used.18. After completing all of the fields on the page, click Next. The next page asks for the database

passwords.19. Provide the SQL Server database administrator password. This is the password associated with

the sa login. By default, the password for this account is blank.20. Provide the Blackboard database user password. This database login is used by the application to

access the database.21. Provide the Blackboard database report user password. This database login is used by the

application to access the reporting database.22. Optional step for Content Collection Users: Provide the content management database password.

This login is used by the application to access content management database.23. After completing all of the fields on the page, click Next. The next page asks where to store the

database data files and the database log files.24. Provide the location where the database data files (.mdf) will be stored. This directory must be on

the database server or on a storage device with a dedicated, high-bandwidth connection to thedatabase server. On a single server installation, the default value isC:\blackboard\mssql\data\. Click Next to accept the default or click Browse to provide anew value and then click Next.

25. Provide the location where the database log files (.ldf) will be stored. This directory must be on thedatabase server or on a storage device with a dedicated, high-bandwidth connection to thedatabase server. On a single server installation, the default value is C:\blackboard\mssql\data\.Click Next to accept the default or click Browse to provide a new value and then click Next.

26. After completing all of the fields on the page, click Next.27. Optional step for Content Collection Users: Provide the storage directories for content

management:

/courses - The default value is blackboard_directory\storage\courses.

/institution - The default value is blackboard_directory\storage\institution.

/library - The default value is blackboard_directory\storage\library.

/orgs - The default value is blackboard_directory\storage\orgs.

/users - The default value is blackboard_directory\storage\users.

28. After completing all of the fields on the page, click Next.29. Provide the Collaboration server hostname. In a one or two server environment, the default value is

the application server. In a load-balanced environment, select one of the existing applicationservers to also act as the Collaboration server. Though not typically required, a separate servermay be dedicated as the Collaboration server exclusively. To learnmore, see Set Up aCollaboration Server. The Collaboration server runs Virtual Classroom and chat sessions.

30. Provide the TCP port number for the Collaboration server. The Collaboration server uses TCP/IPas the preferred communicationmethod for performance reasons. The default port number is 8010.

31. Provide the HTTP port number for the Collaboration server. The Collaboration server uses HTTPas a backupmethod of communication if TCP/IP is not available. The default port number is 8011.

32. After completing all of the fields on the page, click Next.33. Provide the location of the SMTP server and click Next. The SMTP server is used to send out

email communications. Enter the hostname as machine_name.domain_name.


9.1 S

P6 BETA D

RAFT


34. Provide the Blackboard Learn Administrator password. The Administrator account has fullprivileges.

35. Provide the Blackboard Integration password. The integration user is used only to facilitateSnapshot operations. This account cannot be used to log in through theGUI nor does it appear inany lists of users in the user interface. To change the password for this account, on theAdministrator Panel, underBuilding Blocks, click Integration Password.

36. Provide the Blackboard root administrator password. The root_admin account has fulladministrative privileges including themanagement of Virtual Installations through theAdministrator Panel. When the root_admin account user views the Administrator Panel, theManage Virtual Installations link appears at the top of the panel. The root_admin can log in to anyVirtual Installation and access the Virtual Installationmanagement features from this link. While itis necessary to enter a password for this account, it is very rare that a system with VirtualInstallations will be run on one server or two servers.

37. After completing all of the fields on the page, click Next.38. Provide the following information about the administrator and the institution:

l Name and email address of the administratorl Name of Institutionl Type of Institution - The valuemust be one of the following: K-12, Higher Education,

Continuing Education, Corporate, Professional Association, or Hobbyl City, State, Country, and ZIP Code of the institution's address

39. After completing all of the fields on the page, click Next.40. Select the Server Type. This is information is used for better management of centralized services.


41. Click Next.42. Click Next again to install the software. If the Installer was launched from the command line, do not

close the command line window or any of the other windows that pop-up during the installation.

If the Installer failed, check the Installer log and see Troubleshooting to diagnose and fix the problem.

Next StepsMake sure to remove the domain user from the Administrators group on each server. This is a security steprecommended by Microsoft that prevents the domain user, which is used to run services, from acting as anAdministrator.

If a separate storage device has been configured with a UNC path (\\server\share),make sure configurethe services with proper permissions.

Install the Blackboard Learn Software on Additional Application Serverson Windows in a Load-Balanced ConfigurationThe Installer must be runmultiple times to set up each application server. After the first application server andthe database have been installed using the Full Installation option, run the installer again using theAppserver-only Installation option to install the rest of the application servers and the optional Collaborationserver.

The Installer will prompt for the same information as a Full Installation. The installer will not access thedatabase on anAppserver-only Installation, whichmeans that nodes can be added to a load-balancedconfiguration while the system is live.


9.1 S

P6 BETA D

RAFT


When executing the Installer on the additional application servers, pay close attention to the values of the portsand host names. Be sure that the hostname for theWeb server matches the load-balanced URL and is not setto the name of the individual server. Be sure that the Collaboration tool (virtual chat, virtual classroom) ports areset properly. Remember that the following settings must be the same across all application servers (and theCollaboration server):

l Application Server Port Numberl WebServer Port Numberl DatabaseMachine Namel Database Domain Namel SQLServer Instance Namel SQLServer Database Administrator Passwordl Blackboard Database User Passwordl Blackboard Database Report User Passwordl CMS Database User Passwordl Database Data Files Directoryl Database Log Files Directoryl Content Directoryl Content Management Directoriesl Collaboration server Machine Namel Collaboration server http Portl Collaboration server TCP/IP Portl Administrator Passwordl root_admin Passwordl Integration Passwordl Administrator and Institution Details

When the installation is complete, each application server can be accessed individually and tested separately.Complete tests should also be run from the load-balanced URL.

(Optional) Set Up a Clustered Tomcat Environment on Windows in a Load-Balanced ConfigurationTomcat clustering was introduced for scalability purposes when the Blackboard Learn architecture was 32-bitand customers wanted the ability to increase their memory usage on a single server. With the option tovirtualize on both 32-bit and 64-bit, Blackboard’s benchmarking efforts havemoved away from Tomcat clusterdeployments.

Customers can achieve similar performance in a virtual environment on the same physical server with multiplevirtual instances as with a baremetal configuration with many Tomcat cluster instances. The difference inconfigurations is a smaller demand on the Apache or IIS web server fronting the Tomcat instance(s). The optionto deploy a 64-bit JVM with larger heap sizes has suppressed the need for customers to run in a cluster option.


However, new installations can optionally be configured to use a clustered Tomcat environment.

Existing clustered Tomcat environments performing an upgrademust use the following steps.


9.1 S

P6 BETA D

RAFT


How to Set Up an Optional Clustered Tomcat Environment1. Go to blackboard_home\config.2. Open the bb-config.properties file.3. Search for the bbconfig.tomcat.cluster.enable variable.4. Change the default value from FALSE to TRUE.5. Go to blackboard_home\tools\admin.6. Launch the Push Config Updates script by running the PushConfigUpdates.bat file.7. Create a new ServerGroup in Blackboard Learn

a. Go to blackboard_home\tools\admin.b. Create a ServerGroup with a specified port number by running the following command:

ServerGroupManager.bat -c -n new_group_name -p new_port_number

8. Launch the Install Cluster script by running the InstallCluster.bat file. After running the file,you will be prompted for the following information:

a. Cluster ID: Provide a unique ID, such as node1 or node2. It should not be a cluster IDthat is already assigned.

b. Server shutdown port: The default is 8005. Add 1000 to the default to make it 9005. Ifyou already have 9005 in use, use 10005.

c. JK Connector port: The default is 8009. Add 1000 to the default to make it 9009.d. Cluster Listener port: The default is 4000. Add 1000 to the default to make it 5000.

The cluster is now created.

9. Stop your server by running ServiceController.bat services.stop.10. Start your server by running ServiceController.bat services.start.

WARNING! When upgrading an environment with an existing tomcat cluster, the cluster will be broken ifthe ServerGroup is not updated.

How to Remove a Tomcat Cluster1. Go to blackboard_home\tools\admin.2. Stop your server by running ServiceController.bat services.stop.3. Launch the Remove Cluster script by running RemoveCluster.bat.4. Specify the cluster to be deleted, when prompted.

(Optional) Set Up a Collaboration Server for Windows in a Load-BalancedConfigurationThe separate collaboration server is optional because one of the application servers can be used as theCollaboration server.

Complete the following steps to configure a separate Collaboration server.

1. Install an additional application server on amachine that is not configured as part of the load-balanced server environment. This application server must have a hostname separate from themultipleWeb/app configuration host name. Finally, the Collaboration server should be resolvable inthe DNS so that it is accessible from the Internet.


9.1 S

P6 BETA D

RAFT


2. For each application server, set the following property in the bb-config.properties file toprevent the Collaboration server from running on the local host:bbconfig.Collaborationserver.run.on.localhost=false

3. Run the following command:blackboard\tools\admin\PushConfigUpdates.cmd

4. Start the bb-tomcat service on each application server. Do not start the bb-Collaborationservice. The bb-Collaboration servicemust always be stopped on the application servers thatare not acting as the Collaboration server.

5. Repeat steps 2 through 4 for all application servers.6. Stop the bb-tomcat service on the Collaboration server.

Set Up the Blackboard Services on Each Application Server on Windowsin a Load-Balanced ConfigurationThe Blackboard services on each application server must be configured to run with permissions of the 'domainuser' to properly access shared resources.

Follow these steps tomodify the IIS and Blackboard services on each application server.

1. Log on to the first application server as the domain user with administrative privileges.2. Right-click Computer and selectManage.3. Front the Server Manager, click Configuration, and then double-click Services.4. OpenStart > Programs > Administrative Tools > Services.5. Configure the Blackboard Collaboration Service by right clickingBBLEARN-Collab, and then

selectingProperties.6. Click the Log on tab.7. Select This account.8. Browse to and select the domain user.9. Enter and confirm the password for the domain user.10. Click OK.11. Configure the Blackboard Learn Tomcat service by right-clickingBBLEARN-Tomcat, and then

selectingProperties.12. Click the Log on tab.13. Select This account.14. Browse to and select the domain user.15. Enter and confirm the password for the domain user.16. Click OK.17. Repeat these steps for each application server.

Note: When setting up services and using a domain user, go to http://msdn.microsoft.com/en-us/library/ms143504.aspx. If services are not correctly associated to a domain user, it is possible that theservice or services will not start when the server is started.

When PushConfigUpdates is run tomodify configuration parameters, the above changes to the services willneed to be re-applied. To avoid this extra step, add the domain user and password to the Blackboardconfiguration file, bb-config.properties.

The following parameters can be configured with the username (account) and password of the domain user.These are found in the windows - platform configuration section of bb-config.properties:


9.1 S

P6 BETA D

RAFT

http://msdn.microsoft.com/en-us/library/ms143504.aspx



l bbconfig.appserver.service.account.win

l bbconfig.appserver.service.password.win

l bbconfig.Collaborationserver.service.account.win

l bbconfig.Collaborationserver.service.password.win

The user (account) namemust be specified in the form {domainname}\\{username}, or if the accountbelongs to the local computer, specify the name in the form .\\{username}. Alternatively, it can be specifiedas {username}@{fqdn}.

If this section is not configured, repeat the steps in this section after running PushConfigUpdates.

IMPORTANT! After running any updates, ensure that these service settings are still correct.

Set Up the Hardware Load BalancerThe hardware load balancer should be set up according to the instructions included with the load balancer.

When setting up a hardware load balancer, it is important that each application server maintains user sessionaffinity for the entire of the session. Session affinity must be based on the user's cookie. In other words,after a user logs in and a session is created on a particular application server, that server must handle allrequests associated with that session until it is closed.

Test the SystemTest the system by going to a workstation other than any of the Blackboard servers. Open aWeb browser andgo the URL of the shared hostname configured during load balancing setup.

Troubleshooting Windows InstallationThis topic lists some of the common problems that occur during installation and possible solutions.

Log FileThe Installer creates a log file named bb_installer_log.txt. This file is found in theblackboard\logs directory.

If the Installer fails, check the log file to help determine the problem. The log file includes a considerable amountof information about the installation process. Each time the Installer is run, the attempt is appended to the logfile. Make sure to focus on the latest attempt, which will be last in the log file.

Because of the amount of information in the log file, the problemmay not be immediately apparent. Trysearching for the following strings at the bottom of the installation log: BUILD FAILED or Root Cause. Lookclosely at the log file both above and below the search string (BUILD FAILED or Root Cause) for the reasonthe installation failed.

If the log file does not help diagnose the problem, keep a copy of the file in case you need to contact BlackboardLearn Technical Support by logging in to Behind the Blackboard at https://behind.blackboard.com. TechnicalSupport will use the log file to diagnose the problem.

Pages Will Not LoadIf certain pages in Blackboard Learn will not open or take too long to load, do the following to resolve this issue:

Modify theWindows registry and add the following keys:


9.1 S

P6 BETA D

RAFT



1. Click Start > Run > regedit.2. Go to HKEY_LOCAL_

MACHINE\SYSTEM\CurrentControlSet\Services\Tcpip\Parameters.3. Add the following two values:

TcpTimedWaitDelay=dword:0000001e

MaxUserPort=dword:0000fde8

These are DWORD values. After they have been created, you can double-click to edit their Decimalvalues.

Turn off Full Text Search on SQL Server:

1. Click Start > Administrative Tools > Services.2. Stop and disableMicrosoft Search andSQL Server Full Text Search service.

Turn off all network card offload functionality (disable TCP ChecksumOffload):

1. Right-Click My Computer > Properties > Hardware Tab > Device Manager.2. Click Network Adapters > right-click Broadcom BCM5708S NetXtreme II GigE > Properties.3. Click Advanced Tab > Property: Checksum Offload > Value: None.4. Advanced Tab > Property: Large Send Offload > Value: Disable.

Disable network card power saving features:

1. Right-click My Computer > Properties > Hardware Tab > Device Manager.2. Click Network Adapters > right-click Broadcom BCM5708S NetXtreme II GigE > Properties.3. Click Management Tab > Uncheck Allow the computer to turn off this device to save power

> OK.4. Reboot the system.

Turn off the TCP Chimney:

1. Click Start > Run.2. Type cmd, and then press ENTER.3. At the command prompt, type Netsh int ip set chimney DISABLED, and then press

ENTER.

To dynamically turn on TCP Chimney by using the NETsh.exe tool:

1. Click Start > Run.2. Type cmd, and then press ENTER.3. At the command prompt, type Netsh int ip set chimney ENABLED, and then press

ENTER.

Note: To learnmore, consult theMicrosoft Knowledge Base article 912222.

Installation Failure Due to Strict Password Requirements (SQL Server)For an installation with SQL Server, the installationmay fail because of the strict parameters for passwordrequirements. The user will receive the followingmessage:Password validation failed. The password does not meet Windows policyrequirements because it is too short.

To override or reset the password requirements, complete the following steps:


9.1 S

P6 BETA D

RAFT

About the Installation Process > UNIX

1. Create a text file mycustom.properties and add the following line to it (substitute the rightvalue):bbconfig.database.jreport.password=pAssw0rd

2. Run the Installer as follows (text in caps should be filled in as appropriately):java -jar bb-as-PLATFORM-VERSION.jar -config mycustom.properties

Blackboard Support Site and Knowledge BaseThe Blackboard Knowledge Base, which is accessible through Behind the Blackboard athttps://behind.blackboard.com, includes several articles that may address your problem. If a login for Behindthe Blackboard is unavailable, please contact a Blackboard Account Manager.

Contact Blackboard Technical SupportFor information about contacting Blackboard Technical Support, log in to Behind the Blackboard athttps://behind.blackboard.com.

UNIX

Install on UNIX on One or Two ServersThe following section explains the required hardware, software, and necessary steps to properly installBlackboard Learn on one or two UNIX servers. It also includes a section on proper review of the installation andnext steps in administration of the system.

1. Set Up the Hardware and Software2. Configure Oracle

TheOracle media and initiationmust be installed and configuredmanually. Blackboard Learn -Basic Edition clients must install Small-Scale Oracle, which is provided by Blackboard, instead ofOracle. To learnmore, see About Small-Scale Oracle.

3. (Optional) Set Up Database Clustering and Storage4. (Optional) Set Up File System Storage5. Complete the Pre-Installation Checklist6. Complete the Pre-InstallationWorksheet7. Install the Blackboard Learn Application Server and Database Server

Set Up the Hardware and Software on UNIX on One or Two ServersThis section reviews the configuration steps necessary before installing Blackboard Learn.



Required Software


9.1 S

P6 BETA D

RAFT

http://kb.blackboard.com/dashboard.action






For the exact versions of the operating systems, databases, and Java SE Developers Kit (JDK™) that aresupported, see "Supported Technologies" in the Release Notes for the release that you are installing. It iscritical that the software used to host Blackboard Learnmeets requirements.



Create a UNIX User for Blackboard LearnThe Installer requires a user with permissions on the directory where Blackboard Learn will be installed. TheUNIX user must be created prior to installation with the following parameters.

l The user namemust be bbuser.l bbuser must have a valid home directory. Blackboard recommends using /home/bbuser for Linux

operating systems and /export/home/bbuser for Sun Solaris operating systems.

Synchronize Server ClocksCheck the date and time on the system andmake sure it is accurate and that the time zone is set correctly. Ifinstalling on two servers check that the time on the application server and database server match. Rememberthat the servers may be in a different time zone than the users. The server time zone should be the same as thetime zone used by themajority of users, instead of the physical location of the server. Blackboard Learn usesthe server date and time to control the availability of time-sensitivematerials. It is important that users have aclear expectation of whenmaterials will be available and when assignments are due.

PortsBlackboard Learn requires ports to communicate. The list below details the required ports and their defaultvalues. Make sure to configure server security and any firewalls to allow communication on the required ports.



Collaboration server.l Web server SSL port (default: 443): Primary web application port when SSL is in use.l Collaboration server SSL port (default: 8443): Secure communication for the collaboration server.



l Do not use underscores in themachine name for the server or servers. Internet Explorer 6 blockscookies if themachine name includes an underscore.

l Set up the DNS server to resolve server names.l Check with a network engineer to make sure that the network can handle the anticipated load after

Blackboard Learn is made available to users.l An SMTP server must be available so that the Installer can connect to it.


9.1 S

P6 BETA D

RAFT





l An SMTP server has to remain available when the application is running in order to deliver emailnotifications.

Configure Oracle on UNIXThe Blackboard Learn Installer will not install the Oracle media and initial database for the Blackboard schemaby default. Administrators should follow the instructions provided by Oracle for installing the Oracle media anddatabase.

After the Oracle media and database are installed, configuration changes will need to bemade to the Oracleinstance before installing Blackboard Learn.

Oracle has mademany changes to simplify administration responsibilities and improve sophistication of use.

To learnmore about configuring Oracle in a Blackboard Learn environment to achieve the best performancepossible, see Pre-Installation Recommendations in anOracle Environment.

Oracle CompatibilityPrior to Oracle 10g (Release 2), the CONNECT role was granted eight privileges: create session, createtable, create view, create synonym, create database link, create cluster, createsequence, and alter session. With the current release of Oracle, only the create session privilege isgranted to the CONNECT role. Oracle removed the additional privileges granted to the CONNECT role to provideadditional security by enforcing a principle of least privileges.

Standard installations and upgrades require the CONNECT role to have the create session, create

table, create view, create synonym, create sequence, and alter session privileges.Clustered installations and upgrades additionally require the CONNECT role to have the create cluster

privilege. The following script will grant all eight privileges for installations and upgrades of Blackboard Learn onOracle 10g (Release 2). The privileges are only required during the installation or upgrade, andmay be revokedat the time of completion.

sqlplus "/as sysdba"

SQL> @$ORACLE_HOME/rdbms/admin/rstrconn.sql

SQL> commit; SQL> exit

Database Block SizeThe parameter DB_BLOCK_SIZE specifies (in bytes) the size of the Oracle database blocks. This parametermust be set to 8192. Prior installations may have been set to 4096, andmust be changed to 8192. Failure to setthe Oracle database block size 8192 can cause an incorrect installation of Blackboard Learn.

Confirm AL16UTF16 Character SetThe national alternate character set value for Oracle is AL16UTF16 (also referred to as UTF16). Administratorsusing Oracle should confirm that the national alternate character set is AL16UTF16 before installing BlackboardLearn. The National Character Set value can be determined by querying the v$ table using the following SQLcommand:

$ sqlplus ‘/ as sysdba’

SQL> select parameter, value from v$nls_parameters where parameter = ‘NLS_NCHAR_CHARACTERSET’;

PARAMETER Value

--------------------------------------------- ----------------------------------

NLS_NCHAR_CHARACTERSET AL16UTF16


9.1 S

P6 BETA D

RAFT


(Optional) Set Up Database Clustering and Storage for UNIXThese steps are optional. Many institutions will have no need to set up RAC or to set up the data files and indexfiles on a separate storage device. If these options are unnecessary, proceed to the instructions for setting up aseparate file system server.

Oracle RACBlackboard offers support for Oracle RAC with all versions of Oracle supported by Blackboard. To learnmore,see Supported Technologies in the Release Notes for the release that you are installing. For information aboutrunning Blackboard Learn with RAC, seeOracle RAC Support on UNIX.

Setup a Separate Storage Device for the Data Files and Log FilesThe Installer will prompt for the directory where the database data files and log files should be stored. Forinformation about storing these files on a separate device, see theOracle documentation. Keep inmind that thestorage device should have a dedicated, high-bandwidth connection to the database server.

(Optional) Set Up File System Storage for UNIXSetting up file system storage on a separate storage device is an optional step for Blackboard Learn -Enterprise Edition clients.

Note: Blackboard Learn - Basic Edition clients must use the local default location of/usr/local/blackboard/content.

About File System StorageAll of the content files for Blackboard Learn, such as files uploaded to Courses and image files, are stored in theblackboard/content directory. If your school licenses content management, the Content Collection hasseveral content directories, each one dedicated to one of the top-level directories. For example, the /librarydirectory stores all the files for the Library.


These instructions detail how to set up the blackboard/content directory on a separate file server. Thesamemethods can be repeated to set up the content management directories on a separate file server.

How to Set Up Shared File SystemFollow these steps to setup the blackboard/content directory on another server.

1. Log in to the file system server and create a directory that will store the content files.2. Log in to the application server and create amount at usr/local/blackboard/content that

points directly to the content directory on the file system server. Using a symbolic link maycause problems with permissions when using building blocks.

Complete the Pre-Installation Checklist for UNIX on One or Two ServersThe installation checklist and the installation worksheet should be completed before installing Blackboard Learnon one or two servers. Completing both the checklist and the worksheet prior to installation will help ensure asuccessful installation.


9.1 S

P6 BETA D

RAFT




If Blackboard Learn will be installed on only one server, the server must pass the checklist for both theapplication server and the database server.


l A valid Blackboard Learn license file has been downloaded and is accessible from the applicationserver. To receive a license file, contact your Blackboard Client Representative.



Application Server ChecklistReview the following list to make sure that the application server is prepared for installation.

l Themachine is connected to the network and powered on.l Themachinemeets theminimum hardware requirements.l A supported version of the operating system is installed on themachine.l The supported version of JDK is installed on themachine.l Themachine is dedicated to Blackboard Learn and has no unnecessary software installed.l The Administrator has a plan for managing log files.l The Administrator has a plan for backing up the application file system.l The DNS (Domain Name Server) is set to resolve the server name. Note that the server name should

not contain underscore characters. Some versions of Microsoft Internet Explorer 6 block cookiesfrommachines with an underscore in the name.


l The server clock is synchronized with the other server or servers used in Blackboard Learnconfiguration. If the server clocks are not synchronized theremay be differences between thedisplayed availability of time-sensitive content and the actual availability of time-sensitive content.

l A bbuser account has been created.l The bash shell is specified as the bbuser login shell and is also being used by the root user for all

Blackboard Learn tasks including installation.l The Installer can connect to the SMTP server.

Database Server ChecklistReview the following list to make sure that the database server is prepared for installation. Remember that if aone server configuration is used the database server and application server are configured on onemachine.

l Themachinemeets theminimum hardware requirements.l A supported operating system is installed on themachine.l Themachine is dedicated to Blackboard Learn and has no unnecessary software installed.l The database administrator has a plan for backing up the database andmanaging database log files.


9.1 S

P6 BETA D

RAFT



l A supported version of Oracle is installed on themachine. Blackboard Learn - Basic Edition usersmust install Small-Scale Oracle, which is provided by Blackboard. To learnmore, About Small-ScaleOracle. Other Blackboard Learn users must install a supported, full version of Oracle obtainedseparately.

l The database has been created with the necessary initialization parameters.l Oracle Listener and theOracle database are running.l The bash shell is specified as the bbuser login shell and is also being used by the root user for all

Blackboard Learn tasks including installation.l The national (alternate) database character set is AL16UTF16.

Complete the Pre-Installation Worksheet for UNIX on One or Two ServersThe installation worksheet helps identify all of the information required by Installer when installing on one or twoservers. Filling out the worksheet prior to installation will help the installation process run smoothly.



The path to a directory on the application server where Blackboard Learn will reside. Note that the Installer willcreate a directory called blackboard within this directory.

Setup Type: ___________________________________________

Select the Full Installation option to install Blackboard Learn on one or two servers. This option is also usedwhen installing Blackboard Learn on the database and first application server in a Load-Balanced configuration.

License File: ___________________________________________

The path to the License File. If a License File is not available, contact your Blackboard Client Representative torequest one. The License file determines which capabilities are installed. The license file will be detectedautomatically if it is renamed bb-license.xml and placed in the same directory as the Installer.

Java Location: ___________________________________________



The path to the directory where the Blackboard Learn content files associated with Courses, images uploadedto the system, and all other files added to the system will be stored. The default location is/usr/local/blackboard/content. The location can be a share on one of the application servers or onthe database server, or it can be a SAN (storage area network) or NAS (network-attached storage) on aseparate file server. To learnmore about using a separate file server, see Set Up File System Storage forUNIX.



The name of the application server. The Installer will find the name of themachine that the Installer is on andautomatically populate this value. The Installer must be run on the application server.


The name of the domain where theWeb server resides. The application server Machine Name and theapplication server Domain Name form the URL for Blackboard(http://webservermachinename.domain). Because these names form the URL do not use anycharacters other than standard letters and numbers in the application server name or the domain name.Underscores and spaces will cause problems.



9.1 S

P6 BETA D

RAFT


The port that the application engine uses. The default value is 8009. This port is internal to the Blackboardapplication and should not be available to end users.




The domain name andmachine namewhere the Oracle database that Blackboard Learn will use is installed.The databasemachine name can be found the sameway as theWeb server machine name. When installed ona one server configuration, the databasemachine name is the same as the application server machine name.For this reason, the default value is themachine name of the local machine.

Oracle Database Instance Name: ___________________________________________

TheOracle SID where Blackboard Learn databases will reside.

Oracle Database Port: ___________________________________________

TheOracle Database port used by Blackboard Learn to communicate with the database. The default value is1521.

Oracle (sys) System Database Administrator Password: _________________________

TheOracle Database Administrator password.


A password for anOracle user that Blackboard Learn creates at install. This account is also used by theapplication to access the database.


The password for the Database Report User. This is anOracle user that Blackboard Learn uses to access thereporting database.


The password a database user that the Installer creates for content management databases. This value isrequired only if your school licenses content management.


Database identifiers must be unique within the database server. The database identifier is, by default,BBLEARN. If this parameter is left blank, it will default to BBLEARN. This option is not visible during anupgrade, and is typically used exclusively in amulti-tenancy environment. A multi-tenancy environment offersthe ability to host multiple Blackboard Learn instances on a single machine without the data being sharedbetween instances. Multi-tenancy environments are not standard. If you are upgrading your environment andwish to rename your database identifier, please contact Blackboard Support for assistance.

Database Data Directory: ___________________________________________

The directory that will store Blackboard Learn database data files. This directory will not store application dataor content. This directory must be on the database server in a directory where Oracle has read/write/executeprivileges. Make sure that the directory has space to accommodate database growth. This directory must becreated before installing Blackboard Learn.

Database Index Data File Directory: __________________________________________

The directory that will store database index data files. This directory must be on the database server in adirectory where Oracle has read/write/execute privileges. If possible, this directory should be separate from thedata directory.


The path to the content management /courses directory. This directory will store all of the files under the/courses heading. This value is required only if your school licenses content management.


9.1 S

P6 BETA D

RAFT





Enter the path to the content management /library directory. This directory will store all of the files under the/library heading. This value is required only if your school licenses content management.

Orgs Directory: ___________________________________________

The path to the content management /orgs directory. This directory will store all of the files under the /orgsheading. This value is required only if your school licenses content management.

Users Directory: ___________________________________________

The path to the content management /users directory. This directory will store all of the files under the /usersheading. This value is required only if your school licenses content management.


Themachine name that runs the Collaboration Server. It is possible to dual-purpose an existing application toalso serve as the Collaboration Server. Though not typically required, a separate server may be dedicated asthe Collaboration server exclusively. In one server and two server configurations, this machine name is thesame as the application server machine name.





SMTP Server: ___________________________________________

The full hostname (example: smtp.blackboard.com) of the SMTP server that Blackboard Learn will use to sendemails. The parameter bbconfig.email.bitbucket_address=email_addressmust be added and setin the bb-config.properties file to avoid system-generatedmessages, such as enrollment notificationsand discussion board subscriptions from being sent to the administrator. The bit-bucket email address shouldbe set to a valid campus address that has no recipients, failure to use a valid address will result in rejection byemail servers.










9.1 S

P6 BETA D

RAFT









City: ___________________________________________


State: ___________________________________________


ZIP/Postal Code: ___________________________________________


Country: ___________________________________________


Install the Blackboard Learn Application Server and Database Server onUNIXThe Installer is launched from a command line prompt andmay be run in command-linemode or GUI mode. TheInstaller presents a series of questions about the system. Inmany cases, the Installer automatically detectsthe required settings and provides default values. This topic also includes detailed information about the valuesrequired at each Installer prompt.


Before Running the InstallerMake sure that the systemmeets the supported software requirements and is properly configured beforerunning the Installer. To confirm that the system is ready for installation, see Pre-Installation Checklist or Load-Balanced Pre-Installation Checklist.


l Blackboard Learnmust be installed as root. Service startup and shutdownmust also be performed asroot.

l The Installer is run on a two-server system: The instructions reference the application server and thedatabase server. When installing on one server, thesemachines are the same.


9.1 S

P6 BETA D

RAFT


l The Installer is run using the command-line interface: TheGUI Installer requires the same inputs fromthe user. The only difference between the command-line and theGUI interface is navigation. TheGUIinterface uses mouse-clicks instead of using keystrokes to accept a value and continue. Thecommand line places the default or anticipated value in brackets. Youmay either ENTER a new valueor simply press ENTER to select the value in brackets.


How to Run the InstallerFollow the steps below to run the Installer on UNIX:

1. Place both the Installer and the license file in a directory on the application server. The Installer willautomatically recognize the license file if it is renamed bb-license.xml and placed in the samedirectory as the Installer. The following steps use /usr/local/bbinstaller/ as an example.

2. Open a command-line prompt and navigate to the directory that contains the Installer.3. Login as root on the server:

su - root

4. Run the following command to launch the Installer:/usr/local/bbinstaller/java -jar bb-installer.jar

If Xwindows or a similar GUI is running, the Installer will launch in GUI mode. (The following stepsassume that the command line Installer is used). Use the “-text” option to force text mode even if aGUI is running.

5. After reading the welcomemessage, press ENTER to continue.

Instructions display for navigating through the Installer prompts. The Installer, in most cases, willprovide a default value in brackets. Press ENTER to accept the default and continue or ENTER adifferent value. Press ENTER to continue after ENTERing a new value.

6. Provide the directory where Blackboard will be installed. To accept the default value of/usr/local/blackboard, press ENTER. Blackboard does not recommend changing thisdefault.

7. To select the type of installation, type 1 and press ENTER to select Full Installation.8. After reading the License Agreement, type Y and press ENTER to continue the installation. To

refuse the terms of the agreement and close the Installer, type N and press ENTER9. Provide the location of the license file. The Installer will detect the license file and use it as the

default value if the license file is renamed bb-license.xml and placed in the same directory asthe Installer. Press ENTER to accept the default or ENTER a new value and then press ENTER.

10. Provide the location of the JDK. The Installer will use the path that was provided to launch theInstaller.

11. Provide the location of the Shared Content Directory, which is used to store the content filesassociated with Courses, images uploaded to the system, and all other files added to the system.The location can be a share on one of the application servers or on the database server, or it can bea SAN (storage area network) or NAS (network-attached storage) on a separate file server. In aload-balanced configuration, this locationmust be accessible by all of the application servers. Tolearnmore about using a separate file server, see Set Up File System Storage for UNIX. To acceptthe default value of /usr/local/blackboard/content, press ENTER.


12. Provide the name of the application server. The Installer detects themachine name of the server itruns on and uses that to populate the default. Press ENTER to accept the default.


9.1 S

P6 BETA D

RAFT


13. Provide the domain that hosts the application server. The Installer detects this value and populatesthe default. Press ENTER to accept the default.

14. Provide the port number for the application server. This is the port that the application uses forcommunication. The default value is 8009. Press ENTER to accept the default, or provide a newvalue and then press ENTER.

15. Provide the port number for theWeb Server. This is the port that is used for http connections withusers. The default value is 80. Press ENTER to accept the default, or provide a new value and thenpress ENTER.

16. Provide the database server hostname. The default value is the current machine. This is the correctvalue for one server installations. Press ENTER to accept the default if installing on only one server.If installing on two servers, provide a value for the separate databasemachine and press ENTER tocontinue. Keep inmind that the hostname is represented by machine_name.domain_name.

17. Provide the Oracle SID. Provide a value and then press ENTER.18. Provide the Oracle sys database administrator password. Provide a value and then press ENTER.19. Provide the Blackboard database user password. This database login is used by the application to

access the database. Provide a value and then press ENTER.20. Provide the Blackboard database report password. This database login is used by the application to

access the reporting database. ENTER a value and then press ENTER.21. Optional Step for Content Collection Users: Provide the content management database password

and then press ENTER. This login is used by the application to access content managementdatabase.

22. Provide the location for the database data directory and then press ENTER. The directory that willstore Blackboard Learn database data files. This directory will not store application data or content.This directory must be in a directory where Oracle has read/write/execute privileges. Make surethat the directory has space to accommodate database growth. This directory must be createdbefore installing Blackboard Learn.

23. Provide the location for the database index directory and then press ENTER. The directory that willstore Blackboard Learn database index files. This directory must be in a directory where Oracle hasread/write/execute privileges. If possible, this directory should be separate from the data directory.

24. Optional Step for Content Collection Users: Provide the storage directories for the contentmanagement storage locations and then press ENTER. For example, the default value is/usr/local/blackboard/cms/courses.

25. Provide the path to the content management /institution directory. The default value is/usr/local/blackboard/institution. Repeat for each of the four additional locations: Institution, Library, Orgs, and Users.

26. Provide the Collaboration server hostname. In a one or two server environment, the default value isthe application server. In a load-balanced environment, select one of the existing applicationservers to also act as the Collaboration server. Though not typically required, a separate servermay be dedicated as the Collaboration server exclusively. To learnmore, see Set Up aCollaboration Server. The Collaboration server runs Virtual Classroom and chat sessions. PressENTER to accept the default or provide a new value and then press ENTER.

27. Provide the TCP port number for the Collaboration server. The default port number is 8010. PressENTER to accept the default or provide a new value and then press ENTER.

28. Provide the HTTP port number for the Collaboration server. The default port number is 8011. PressENTER to accept the default or provide a new value and then press ENTER.

29. Provide the hostname of the SMTP server. The SMTP server is used to send out emailcommunications. Keep inmind that the hostname is the represented by machine_name.domain_name. Provide a value and then press ENTER.


9.1 S

P6 BETA D

RAFT


30. Provide the Blackboard Administrator password. The Administrator account has full privileges.Provide a value and then press ENTER.

31. Provide the Blackboard Integration password. The integration user is used only to facilitateSnapshot operations. This account cannot be used to log in through theGUI nor does it appear inany lists of users in the user interface. To change the password for this account, on theAdministrator Panel, underBuilding Blocks, click Integration Password. Provide a value andthen press ENTER.

32. Provide the Blackboard root administrator password. The root_admin account has fulladministrative privileges including themanagement of Virtual Installations through theAdministrator Panel. When the root_admin account user views the Administrator Panel, theManage Virtual Installations link appears at the top of the panel. The root_admin can log in to anyVirtual Installation and access the Virtual Installationmanagement features from this link. While itis necessary to ENTER a password for this account, it is very rare that a system with VirtualInstallations will be run on one server or two servers. Provide a value and then press ENTER.

33. Follow the prompts to ENTER the administrator's contact information.34. ENTER the Server Type. This is information is used for better management of centralized services.


35. Press ENTER to install the software. Do not close the command line window during the installation.

If the Installer failed, please check the Installer log and see Troubleshooting to diagnose and fix the problem.

Install on UNIX in a Load-Balanced ConfigurationThe following section explains the required hardware, software, and necessary steps to properly installBlackboard Learn on UNIX on a load-balanced configuration. It also includes a section on proper review of theinstallation and next steps in administration of the system.

1. Set Up the Hardware and Software2. Configure Oracle

TheOracle media and initiationmust be installed and configuredmanually. Blackboard Learn -Basic Edition clients must install Small-Scale Oracle, which is provided by Blackboard, instead ofOracle 10g. To learnmore, contact Blackboard Learn Technical Support by logging in to Behind theBlackboard at https://behind.blackboard.com.

3. (Optional) Set Up Database Clustering and Storage4. (Optional) Set Up File System Storage5. Complete the Pre-Installation Checklist6. Complete the Pre-InstallationWorksheet7. Install the Blackboard Learn Application Server and Database8. Install the Blackboard Learn Software on Additional Application Servers9. (Optional) Set Up a Clustered Tomcat Environment10. (Optional) Install the Separate Collaboration Server11. Set Up the Hardware Load Balancer


9.1 S

P6 BETA D

RAFT



Set Up the Hardware and Software on UNIX in a Load-BalancedConfigurationA load-balanced configuration requires that the first application server and database server be installed usingthe two server configurationmodel. After that, the Installer can be run again on each additional applicationserver to install only those components. Each additional Web/application server must alsomeet the requiredprerequisites.

Make sure that the hardware, software, and network are prepared before beginning to configure and installBlackboard Learn in a load-balanced environment.

Required HardwareAbout Hardware Sizing in a Dell Environment and About Hardware Sizing in a SunMicrosystems Environmentdetail several different hardware configurations based on performance, cost, and redundancy. Read thisdocument to make sure that the planned hardware configurationmeets the needs of the institution.




Download and install the JDK on each application server.


Collaboration ServerSelect one of the existing application servers to also act as the Collaboration server. Optionally, configure aseparate Collaboration server. To learnmore, see Set Up a Collaboration Server. The Collaboration server maynot be spread across multiple application servers because all users participating in a Collaboration sessionmust share the same resources. A single server must be configured to run the Collaboration server. This servermust handle Collaboration sessions and performance will be unaffected by other requests. The applicationservers are configured to connect users to one server that handles all the Collaboration sessions.

Do not connect the Collaboration server to the load-balancer.

Dedicated File System ServerSet aside one server as a dedicated file system server. The content files must be centralized so that all files areavailable to users regardless of the application server handling the connection. The application servers areconfigured to find the content files in a directory on the file system server.

Load-Balancing MethodsInstitutions can use the load-balancingmethod of their choice as long as it adheres to a few basic principles:

l The load-balancingmethodmust use cookie-based session affinity.l If SSL is used, the same certificate must be shared by all the application servers. More information

about SSL can be found in About SSL and SSLChoice. Do not use the "SSL acceleration" or "SSLoff-load" features of the load-balancer.


9.1 S

P6 BETA D

RAFT





l The /etc/hosts file must have an entry for the virtual IP’s hostname that points to the localhost(127.0.0.1).

Create a UNIX User for Blackboard LearnThe Installer requires a user with permissions on the directory where Blackboard Learn will be installed. TheUNIX user must be created prior to installation with the following parameters.

l The user namemust be bbuser.l bbuser must have a valid home directory. Blackboard recommends using /home/bbuser for Linux

operating systems and /export/home/bbuser for Sun Solaris operating systems.

Synchronize Server ClocksCheck the date and time on the system andmake sure it is accurate and that the time zone is set correctly. Ifinstalling on two servers check that the time on the application server and database server match. Rememberthat the servers may be in a different time zone than users. The server time zone should be the same as thetime zone used by themajority of users, instead of the physical location of the server. Blackboard Learn usesthe server date and time to control the availability of time-sensitivematerials. It is important that users have aclear expectation of whenmaterials will be available and when assignments are due.

PortsBlackboard Learn requires ports to communicate. The list below details the required ports and their defaultvalues. Make sure to configure server security and any firewalls to allow communication on the required ports.The port values must be the same for each application server.



Collaboration server.l Web server SSL port (default: 443): Primary web application port when SSL is in use.l Collaboration server SSL port (default: 8443): Secure communication for the collaboration server.



l Do not use underscores in themachine name for the server or servers. Some versions of InternetExplorer block cookies if themachine name includes an underscore.

l Set up the DNS server to resolve the hardware load-balancer. The hardware load-balancer will thendirect traffic to the application servers. Set up a separate DNS entry for the Collaboration server.

l Check with a network engineer to make sure that the network can handle the anticipated load afterBlackboard Learn is made available to users.

l An SMTP server must be available so that the Installer can connect to it.l An SMTP server has to remain available when the application is running in order to deliver email

notifications.


9.1 S

P6 BETA D

RAFT


Configure Oracle on UNIXThe Blackboard Learn Installer will not install the Oracle media and initial database for the Blackboard schemaby default. Administrators should follow the instructions provided by Oracle for installing the Oracle media anddatabase.

After the Oracle media and database are installed, configuration changes will need to bemade to the Oracleinstance before installing Blackboard Learn.

Oracle has mademany changes to simplify administration responsibilities and improve sophistication of use.

To learnmore about configuring Oracle in a Blackboard Learn environment to achieve the best performancepossible, see Pre-Installation Recommendations in anOracle Environment.

Oracle CompatibilityPrior to Oracle 10g (Release 2), the CONNECT role was granted eight privileges: create session, createtable, create view, create synonym, create database link, create cluster, createsequence, and alter session. With the current release of Oracle, only the create session privilege isgranted to the CONNECT role. Oracle removed the additional privileges granted to the CONNECT role to provideadditional security by enforcing a principle of least privileges.

Standard installations and upgrades require the CONNECT role to have the create session, create

table, create view, create synonym, create sequence, and alter session privileges.Clustered installations and upgrades additionally require the CONNECT role to have the create cluster

privilege. The following script will grant all eight privileges for installations and upgrades of Blackboard Learn onOracle 10g (Release 2). The privileges are only required during the installation or upgrade, andmay be revokedat the time of completion.



SQL> commit; SQL> exit

Database Block SizeThe parameter DB_BLOCK_SIZE specifies (in bytes) the size of the Oracle database blocks. This parametermust be set to 8192. Prior installations may have been set to 4096, andmust be changed to 8192. Failure to setthe Oracle database block size 8192 can cause an incorrect installation of Blackboard Learn.

Confirm AL16UTF16 Character SetThe national alternate character set value for Oracle is AL16UTF16 (also referred to as UTF16). Administratorsusing Oracle should confirm that the national alternate character set is AL16UTF16 before installing BlackboardLearn. The National Character Set value can be determined by querying the v$ table using the following SQLcommand:



PARAMETER Value

--------------------------------------------- ----------------------------------



9.1 S

P6 BETA D

RAFT


(Optional) Set Up Database Clustering and Storage for UNIXThese steps are optional. Many institutions will have no need to set up RAC or to set up the data files and indexfiles on a separate storage device. If these options are unnecessary, proceed to the instructions for setting up aseparate file system server.

Oracle RACBlackboard offers support for Oracle RAC with all versions of Oracle supported by Blackboard. To learnmore,see Supported Technologies in the Release Notes for the release that you are installing. For information aboutrunning Blackboard Learn with RAC, seeOracle RAC Support on UNIX.

Setup a Separate Storage Device for the Data Files and Log FilesThe Installer will prompt for the directory where the database data files and log files should be stored. Forinformation about storing these files on a separate device, see theOracle documentation. Keep inmind that thestorage device should have a dedicated, high-bandwidth connection to the database server.

(Optional) Set Up File System Storage for UNIXSetting up file system storage on a separate storage device is an optional step for Blackboard Learn -Enterprise Edition clients.

Note: Blackboard Learn - Basic Edition clients must use the local default location of/usr/local/blackboard/content.

About File System StorageAll of the content files for Blackboard Learn, such as files uploaded to Courses and image files, are stored in theblackboard/content directory. If your school licenses content management, the Content Collection hasseveral content directories, each one dedicated to one of the top-level directories. For example, the /librarydirectory stores all the files for the Library.


These instructions detail how to set up the blackboard/content directory on a separate file server. Thesamemethods can be repeated to set up the content management directories on a separate file server.

How to Set Up Shared File SystemFollow these steps to setup the blackboard/content directory on another server.

1. Log in to the file system server and create a directory that will store the content files.2. Log in to the application server and create amount at usr/local/blackboard/content that

points directly to the content directory on the file system server. Using a symbolic link maycause problems with permissions when using building blocks.

Complete the Pre-Installation Checklist for UNIX in a Load-BalancedConfigurationThe installation checklist and the installation worksheet should be completed before installing BlackboardLearn. Completing both the checklist and the worksheet prior to installation will help ensure a successfulinstallation.


9.1 S

P6 BETA D

RAFT





l A valid Blackboard Learn license file has been downloaded and is accessible from the applicationserver. To receive a license file, contact your Blackboard Client Representative.



Application Server ChecklistReview the following list to make sure that each application server is prepared for installation.

l Themachine is connected to the network and powered on.l Themachinemeets theminimum hardware requirements.l A supported version of the operating system is installed on themachine.l The supported version of JDK is installed on themachine.l Themachine is dedicated to Blackboard Learn and has no unnecessary software installed.l The Administrator has a plan for managing log files.l The DNS (Domain Name Server) is set to resolve the name of the load-balancer.l Any firewalls are configured to allow access to Blackboard Learn ports. These ports are defined when

the Installer is run. It is not possible to use a firewall to redirect to a different port. Blackboard Learnmust be available to users on the ports specified during the installation and not served through analternate port.


l A bbuser account has been created.l The bash shell is specified as the bbuser login shell and is also being used by the root user for all

Blackboard Learn tasks including installation.l The Installer can connect to the SMTP server.l If using a clustered Tomcat environment, the Server Groups, and Ports have been configured. This is

especially important when upgrading an existing clustered Tomcat environment.

File System Server ChecklistReview the following list to make sure that the file system server is prepared for installation.

l The Administrator has a plan for backing up the application file system.l A directory to store the Blackboard content is configured and shared. Another directory for the content

management content (available only if your school licenses content management is configured andshared, if desired.

l The domain user that will run the application services has full access to the shared directories.

Collaboration Server ChecklistReview the following list to make sure that the Collaboration server is prepared for installation.

l The Collaboration server uses a different DNS name than that of the application servers.


9.1 S

P6 BETA D

RAFT



Database Server ChecklistReview the following list to make sure that the database server is prepared for installation. Remember that if aone server configuration is used, the database server and application server are configured on onemachine.

l Themachinemeets theminimum hardware requirements.l A supported operating system is installed on themachine.l Themachine is dedicated to Blackboard Learn and has no unnecessary software installed.l The database administrator has a plan for backing up the database andmanaging database log files.l A supported version of Oracle is installed on themachine. Blackboard Learn - Basic Edition users

must install Small-Scale Oracle, which is provided by Blackboard. To learnmore, contact BlackboardLearn Support. Other Blackboard Learn users must install a supported, full version of Oracle obtainedseparately.

l The database has been created with the necessary initialization parameters.l Oracle Listener and theOracle database are running.l The bash shell is specified as the bbuser login shell and is also being used by the root user for all

Blackboard Learn tasks including installation.l The national (alternate) database character set is AL16UTF16.

Complete the Pre-Installation Worksheet on UNIX in a Load-BalancedConfigurationThe installation worksheet helps identify all of the information required by the Installer. Filling out the worksheetprior to installation will help the installation process run smoothly.

Note: Most of the values required by the Installer must be the same for each application server and for theCollaboration server. All ports and settings that point to the database server, Collaboration server, and filesystem server must be the same for all.



The path to a directory on the application server where Blackboard Learn will reside. Note that the Installer willcreate a directory called blackboard within this directory.

Setup Type: ___________________________________________

Select one of the following options:

l Full Installation: Select this option to install the database and the first application server.l Appserver-only Installation Select this option when installing the second and all subsequent

application servers or when setting up the Collaboration server on a separate device.

License File: ___________________________________________

The path to the License File. If a License File is not available, contact Blackboard Client Representative torequest one. The License file determines which capabilities are installed. The license file will be automaticallydetected if it is renamed bb-license.xml and placed in the same directory as the Installer.

Java Location: ___________________________________________



The path to the directory where the Blackboard Learn content files associated with Courses, images uploadedto the system, and all other files added to the system will be stored. The default location is


9.1 S

P6 BETA D

RAFT


/usr/local/blackboard/content. The location can be a share on one of the application servers or onthe database server, or it can be a SAN (storage area network) or NAS (network-attached storage) on aseparate file server. In a load-balanced configuration, this locationmust be accessible by all of the applicationservers. To learnmore about using a separate file server, see Set Up File System Storage for UNIX.



The name of the application server. The Installer will find the name of themachine that the Installer is on andautomatically populate this value. The Installer must be run on the application server.


The name of the domain where theWeb server resides. The application server Machine Name and theapplication server Domain Name form the URL for Blackboard(http://webservermachinename.domain). Because these names form the URL do not use anycharacters other than standard letters and numbers (underscores and spaces will cause problems) in theapplication server name or the domain name.


The port that the application engine uses. The default value is 8009. This port is internal to the Blackboardapplication and should not be available to end users.




The domain name andmachine namewhere the Oracle database that Blackboard Learn will use is installed.The databasemachine name can be found the sameway as theWeb server machine name. When installed ona one server configuration, the databasemachine name is the same as the application server machine name.For this reason, the default value is themachine name of the local machine.

Oracle Database Instance Name: ___________________________________________

TheOracle SID where Blackboard Learn databases will reside.

Oracle Database Port: ___________________________________________

TheOracle Database port used by Blackboard Learn to communicate with the database. The default value is1521.

Oracle (sys) System Database Administrator Password: _________________________

TheOracle Database Administrator password.


A password for anOracle user that Blackboard Learn creates at install. This account is also used by theapplication to access the database.


The password for the Database Report User. This is anOracle user that Blackboard Learn uses to access thereporting database.


The password for the database user the Installer creates for the content management databases. This value isrequired only if your school licenses content management.


Database identifiers must be unique within the database server. The database identifier is, by default,BBLEARN. If this parameter is left blank, it will default to BBLEARN. This option is not visible during anupgrade, and is typically used exclusively in amulti-tenancy environment. A multi-tenancy environment offers


9.1 S

P6 BETA D

RAFT


the ability to host multiple Blackboard Learn instances on a single machine without the data being sharedbetween instances. Multi-tenancy environments are not standard. If you are upgrading your environment andwish to rename your database identifier, please contact Blackboard Support for assistance.

Database Data Directory: ___________________________________________

The directory that will store Blackboard Learn database data files. This directory will not store application dataor content. This directory must be on the database server in a directory where Oracle has read/write/executeprivileges. Make sure that the directory has space to accommodate database growth. This directory must becreated before installing Blackboard Learn.

Database Index Data File Directory: __________________________________________

The directory that will store database index data files. This directory must be on the database server in adirectory where Oracle has read/write/execute privileges. If possible, this directory should be separate from thedata directory.


The path to the content management /courses directory. This directory will store all of the files under the/courses heading. This value is required only if your school licenses content management.



Library Directory:: ___________________________________________

The path to the content management /library directory. This directory will store all of the files under the/library heading. This value is required only if your school licenses content management.

Orgs Directory: ___________________________________________

The path to the content management /orgs directory. This directory will store all of the files under the /orgsheading. This value is required only if your school licenses content management.

Users Directory: ___________________________________________

The path to the content management /users directory. This directory will store all of the files under the /usersheading. This value is required only if your school licenses content management.


Themachine name that runs the Collaboration Server. It is possible to dual-purpose an existing application toalso serve as the Collaboration Server. Though not typically required, a separate server may be dedicated asthe Collaboration server exclusively. In Load-Balanced configurations, it is important to direct all CollaborationTool traffic to one server to maintain session integrity across users.





SMTP Server: ___________________________________________

The full hostname (example: smtp.blackboard.com) of the SMTP server that Blackboard Learn will use to sendemails. The parameter bbconfig.email.bitbucket_address=email_addressmust be added and setin the bb-config.properties file to avoid system-generatedmessages, such as enrollment notificationsand discussion board subscriptions from being sent to the administrator. The bit-bucket email address shouldbe set to a valid campus address that has no recipients, failure to use a valid address will result in rejection byemail servers.



9.1 S

P6 BETA D

RAFT
















City: ___________________________________________


State: ___________________________________________


ZIP/Postal Code: ___________________________________________


Country: ___________________________________________


Install the Blackboard Learn Application Server and Database Server onUNIXThe Installer is launched from a command line prompt andmay be run in command-linemode or GUI mode. TheInstaller presents a series of questions about the system. Inmany cases, the Installer automatically detectsthe required settings and provides default values. This topic also includes detailed information about the valuesrequired at each Installer prompt.


9.1 S

P6 BETA D

RAFT



Before Running the InstallerMake sure that the systemmeets the supported software requirements and is properly configured beforerunning the Installer. To confirm that the system is ready for installation, see Pre-Installation Checklist or Load-Balanced Pre-Installation Checklist.


l Blackboard Learnmust be installed as root. Service startup and shutdownmust also be performed asroot.

l The Installer is run on a two-server system: The instructions reference the application server and thedatabase server. When installing on one server, thesemachines are the same.

l The Installer is run using the command-line interface: TheGUI Installer requires the same inputs fromthe user. The only difference between the command-line and theGUI interface is navigation. TheGUIinterface uses mouse-clicks instead of using keystrokes to accept a value and continue. Thecommand line places the default or anticipated value in brackets. Youmay either ENTER a new valueor simply press ENTER to select the value in brackets.


How to Run the InstallerFollow the steps below to run the Installer on UNIX:

1. Place both the Installer and the license file in a directory on the application server. The Installer willautomatically recognize the license file if it is renamed bb-license.xml and placed in the samedirectory as the Installer. The following steps use /usr/local/bbinstaller/ as an example.

2. Open a command-line prompt and navigate to the directory that contains the Installer.3. Login as root on the server:

su - root

4. Run the following command to launch the Installer:/usr/local/bbinstaller/java -jar bb-installer.jar

If Xwindows or a similar GUI is running, the Installer will launch in GUI mode. (The following stepsassume that the command line Installer is used). Use the “-text” option to force text mode even if aGUI is running.

5. After reading the welcomemessage, press ENTER to continue.

Instructions display for navigating through the Installer prompts. The Installer, in most cases, willprovide a default value in brackets. Press ENTER to accept the default and continue or ENTER adifferent value. Press ENTER to continue after ENTERing a new value.

6. Provide the directory where Blackboard will be installed. To accept the default value of/usr/local/blackboard, press ENTER. Blackboard does not recommend changing thisdefault.

7. To select the type of installation, type 1 and press ENTER to select Full Installation.8. After reading the License Agreement, type Y and press ENTER to continue the installation. To

refuse the terms of the agreement and close the Installer, type N and press ENTER


9.1 S

P6 BETA D

RAFT


9. Provide the location of the license file. The Installer will detect the license file and use it as thedefault value if the license file is renamed bb-license.xml and placed in the same directory asthe Installer. Press ENTER to accept the default or ENTER a new value and then press ENTER.

10. Provide the location of the JDK. The Installer will use the path that was provided to launch theInstaller.

11. Provide the location of the Shared Content Directory, which is used to store the content filesassociated with Courses, images uploaded to the system, and all other files added to the system.The location can be a share on one of the application servers or on the database server, or it can bea SAN (storage area network) or NAS (network-attached storage) on a separate file server. In aload-balanced configuration, this locationmust be accessible by all of the application servers. Tolearnmore about using a separate file server, see Set Up File System Storage for UNIX. To acceptthe default value of /usr/local/blackboard/content, press ENTER.


12. Provide the name of the application server. The Installer detects themachine name of the server itruns on and uses that to populate the default. Press ENTER to accept the default.

13. Provide the domain that hosts the application server. The Installer detects this value and populatesthe default. Press ENTER to accept the default.

14. Provide the port number for the application server. This is the port that the application uses forcommunication. The default value is 8009. Press ENTER to accept the default, or provide a newvalue and then press ENTER.

15. Provide the port number for theWeb Server. This is the port that is used for http connections withusers. The default value is 80. Press ENTER to accept the default, or provide a new value and thenpress ENTER.

16. Provide the database server hostname. The default value is the current machine. This is the correctvalue for one server installations. Press ENTER to accept the default if installing on only one server.If installing on two servers, provide a value for the separate databasemachine and press ENTER tocontinue. Keep inmind that the hostname is represented by machine_name.domain_name.

17. Provide the Oracle SID. Provide a value and then press ENTER.18. Provide the Oracle sys database administrator password. Provide a value and then press ENTER.19. Provide the Blackboard database user password. This database login is used by the application to

access the database. Provide a value and then press ENTER.20. Provide the Blackboard database report password. This database login is used by the application to

access the reporting database. ENTER a value and then press ENTER.21. Optional Step for Content Collection Users: Provide the content management database password

and then press ENTER. This login is used by the application to access content managementdatabase.

22. Provide the location for the database data directory and then press ENTER. The directory that willstore Blackboard Learn database data files. This directory will not store application data or content.This directory must be in a directory where Oracle has read/write/execute privileges. Make surethat the directory has space to accommodate database growth. This directory must be createdbefore installing Blackboard Learn.

23. Provide the location for the database index directory and then press ENTER. The directory that willstore Blackboard Learn database index files. This directory must be in a directory where Oracle hasread/write/execute privileges. If possible, this directory should be separate from the data directory.

24. Optional Step for Content Collection Users: Provide the storage directories for the contentmanagement storage locations and then press ENTER. For example, the default value is/usr/local/blackboard/cms/courses.


9.1 S

P6 BETA D

RAFT


25. Provide the path to the content management /institution directory. The default value is/usr/local/blackboard/institution. Repeat for each of the four additional locations: Institution, Library, Orgs, and Users.

26. Provide the Collaboration server hostname. In a one or two server environment, the default value isthe application server. In a load-balanced environment, select one of the existing applicationservers to also act as the Collaboration server. Though not typically required, a separate servermay be dedicated as the Collaboration server exclusively. To learnmore, see Set Up aCollaboration Server. The Collaboration server runs Virtual Classroom and chat sessions. PressENTER to accept the default or provide a new value and then press ENTER.

27. Provide the TCP port number for the Collaboration server. The default port number is 8010. PressENTER to accept the default or provide a new value and then press ENTER.

28. Provide the HTTP port number for the Collaboration server. The default port number is 8011. PressENTER to accept the default or provide a new value and then press ENTER.

29. Provide the hostname of the SMTP server. The SMTP server is used to send out emailcommunications. Keep inmind that the hostname is the represented by machine_name.domain_name. Provide a value and then press ENTER.

30. Provide the Blackboard Administrator password. The Administrator account has full privileges.Provide a value and then press ENTER.

31. Provide the Blackboard Integration password. The integration user is used only to facilitateSnapshot operations. This account cannot be used to log in through theGUI nor does it appear inany lists of users in the user interface. To change the password for this account, on theAdministrator Panel, underBuilding Blocks, click Integration Password. Provide a value andthen press ENTER.

32. Provide the Blackboard root administrator password. The root_admin account has fulladministrative privileges including themanagement of Virtual Installations through theAdministrator Panel. When the root_admin account user views the Administrator Panel, theManage Virtual Installations link appears at the top of the panel. The root_admin can log in to anyVirtual Installation and access the Virtual Installationmanagement features from this link. While itis necessary to ENTER a password for this account, it is very rare that a system with VirtualInstallations will be run on one server or two servers. Provide a value and then press ENTER.

33. Follow the prompts to ENTER the administrator's contact information.34. ENTER the Server Type. This is information is used for better management of centralized services.


35. Press ENTER to install the software. Do not close the command line window during the installation.

If the Installer failed, please check the Installer log and see Troubleshooting to diagnose and fix the problem.

Install the Blackboard Learn Software on Additional Application Serverson UNIX in a Load-Balanced ConfigurationThe Installer must be runmultiple times to set up each application server. After the first application server andthe database have been installed using the Full Installation option, run the installer again using theAppserver-only Installation option to install the rest of the application servers and the optional Collaborationserver.

The Installer will prompt for the same information as a Full Installation. The installer will not access thedatabase on anAppserver-only Installation, whichmeans that nodes can be added to a load-balancedconfiguration while the system is live.


9.1 S

P6 BETA D

RAFT


Keep the following points in mind:l Blackboard Learnmust be installed as root. Service startup and shutdownmust also be performed as

root.l Experienced administrators may choose to use the non-interactive Installer to setup the second and

subsequent application servers.

When executing the Installer on the additional application servers, pay close attention to the values of the portsand host names. Be sure that the hostname for theWeb server matches the load-balanced URL and is not setto the name of the individual server. Be sure that the Collaboration tool (virtual chat, virtual classroom) ports areset properly. Remember that the following settings must be the same across all application servers (and theCollaboration server):

l Application Server Port Numberl WebServer Port Numberl DatabaseMachine Namel Database Domain Namel Oracle Database Passwordl Blackboard Database User Passwordl Blackboard Database Report User Passwordl CMS Database User Passwordl Database Data Files Directoryl Database Log Files Directoryl Content Directoryl Content Management Directoriesl Collaboration server Machine Namel Collaboration server http Portl Collaboration server TCP/IP Portl Administrator Passwordl root admin Passwordl Integration Passwordl Administrator and Institution Details

When the installation is complete, each application server can be accessed individually and separately tested;complete tests should also be run from the load-balanced URL.

(Optional) Set Up a Clustered Tomcat Environment on UNIX in a Load-Balanced ConfigurationTomcat clustering was introduced for scalability purposes when the Blackboard Learn architecture was 32-bitand customers wanted the ability to increase their memory usage on a single server. With the option tovirtualize on both 32-bit and 64-bit, Blackboard’s benchmarking efforts havemoved away from Tomcat clusterdeployments.

Customers can achieve similar performance in a virtual environment on the same physical server with multiplevirtual instances as with a baremetal configuration with many Tomcat cluster instances. The difference inconfigurations is a smaller demand on the Apache or IIS web server fronting the Tomcat instance(s). The optionto deploy a 64-bit JVM with larger heap sizes has suppressed the need for customers to run in a cluster option.


9.1 S

P6 BETA D

RAFT



However, new installations can optionally be configured to use a clustered Tomcat environment.

Existing clustered Tomcat environments performing an upgrademust use the following steps.

How to Set Up an Optional Clustered Tomcat Environment1. Go to the Blackboard Learn home, /usr/local/blackboard/config.2. Open the bb-config.properties file.3. Search for the bbconfig.tomcat.cluster.enable variable, andmodify the default value

from FALSE to TRUE.4. Go to blackboard_home/tools/admin.5. Launch the Push Config Updates script by issuing ./PushConfigUpdates.sh.6. Create a new ServerGroup in Blackboard Learn

a. Go to blackboard_home/tools/admin.b. Create a ServerGroup with a specified port number by issuing:

./ServerGroupManager.sh -c -n new_group_name -p new_port_number

7. Launch the Install Cluster script by issuing ./InstallCluster.sh. After running the command,you will be prompted for the following information.

a. Cluster ID: Provide a unique ID, such as node1 or node2. It should not be a cluster ID that is already assigned.

b. Server shutdown port: The default is 8005. Add 1000 to the default to make it 9005. Ifyou already have 9005 in use, use 10005.

c. JK Connector port: The default is 8009. Add 1000 to the default to make it 9009.d. Cluster Listener port: The default is 4000. Add 1000 to the default to make it 5000.

The cluster is now created.

8. Stop your server by issuing ./ServiceController.sh services.stop.9. Start your server by issuing ./ServiceController.sh services.start.10. Run the jps command from JAVA_HOME to see the bootstrap processes. You should see one

Tomcat Process, and the number of Cluster Process IDs.

WARNING! When upgrading an environment with an existing tomcat cluster, the cluster will be broken ifthe ServerGroup is not updated.

How to Remove a Tomcat Cluster1. Go to blackboard_home/tools/admin.2. Stop your server by issuing./ServiceController.sh services.stop .3. Launch the Remove Cluster script by issuing ./RemoveCluster.sh.4. Specify the cluster to be deleted, when prompted.5. Verify the cluster was successfully removed by running the jps command from JAVA_HOME to

see the bootstrap processes.


9.1 S

P6 BETA D

RAFT


(Optional) Set Up a Collaboration Server for UNIX in a Load-BalancedConfigurationThe separate collaboration server is optional because one of the application servers can be used as theCollaboration server.

Complete the following steps to configure a separate Collaboration server.

1. Install an additional application server on amachine that is not configured as part of the load-balanced server environment. This application server must have a hostname separate from themultipleWeb/app configuration host name. Finally, the Collaboration server should be resolvable inthe DNS so that it is accessible from the Internet.

2. For each application server, set the following property in the bb-config.properties file toprevent the Collaboration server from running on the local host.bbconfig.Collaborationserver.run.on.localhost=false

3. Run the following command:\blackboard\tools\admin\PushConfigUpdates.bat

4. Start the bb-tomcat and IIS services on each application server. Do not start the bb-Collaboration service. The bb-Collaboration servicemust always be stopped on theapplication servers that are not acting as the Collaboration server.

5. Repeat steps 2 through 4 for all application servers.6. Stop the bb-tomcat service on the Collaboration server.

Set Up the Hardware Load BalancerThe hardware load balancer should be set up according to the instructions included with the load balancer.

When setting up a hardware load balancer, it is important that each application server maintains user sessionaffinity for the entire of the session. Session affinity must be based on the user's cookie. In other words,after a user logs in and a session is created on a particular application server, that server must handle allrequests associated with that session until it is closed.

Test the SystemTest the system by going to a workstation other than any of the Blackboard servers. Open aWeb browser andgo the URL of the shared hostname configured during load balancing setup.

Troubleshooting UNIX InstallationThis topic lists some of the common problems that occur during installation and possible solutions.

Log FileThe Installer creates a log file named bb_installer_log.txt. This file is found in theblackboard/logs directory.

If the Installer fails, check the log file to help determine the problem. The log file includes a considerable amountof information about the installation process. Each time the Installer is run, the attempt is appended to the logfile. Make sure to focus on the latest attempt, which will be last in the log file.

Because of the amount of information in the log file, the problemmay not be immediately apparent. Trysearching for the following strings at the bottom of the installation log: BUILD FAILED or Root Cause. Look


9.1 S

P6 BETA D

RAFT

About the Installation Process > Uninstalling Blackboard Learn

closely at the log file both above and below the search string (BUILD FAILED or Root Cause) for the reasonthe installation failed.

If the log file does not help diagnose the problem, keep a copy of the file in case you need to contact BlackboardTechnical Support by logging in to Behind the Blackboard at https://behind.blackboard.com. Technical Supportwill use the log file to diagnose the problem.

Blackboard Support Site and Knowledge BaseThe Blackboard Knowledge Base, which is accessible through Behind the Blackboard athttp://behind.blackboard.com, includes several articles that may address your problem. If a login for Behind theBlackboard is unavailable, please contact a Blackboard Account Manager.

Contact Blackboard Technical SupportFor information about contacting Blackboard Technical Support, log in to Behind the Blackboard athttps://behind.blackboard.com.

Uninstalling Blackboard LearnThe Installer and Updater includes two uninstall functions.

l Uninstall completely removes the application files, content files, and the database.l Uninstall App Server Only uninstalls only the application files, and leaves the content files and

database. Typically, Uninstall App Server Only is used as part of the process when uninstalling aload-balanced system. However, it can be useful to uninstall the application files and save thecontent files and databases for archiving.

Note: As a best practice, Blackboard recommends that instead of uninstalling, you re-image the applicationand database servers and then perform a fresh operating system installation.

Before Running the Uninstaller on UNIXIt is important to close all Blackboard Learn-related sessions that are connected to the Oracle database. Followthese steps to disconnect related sessions:

1. Login as root:su - root

2. Stop all Blackboard Learn services.3. Terminate database connections by shutting down and restarting Oracle Database Server.

-or-Issue the following SQL command to find connected sessions:

SQL>select process from v$session where schemaname IN (‘BBADMIN’,’BB_BB60’,’BB_BB60_STATS’);

Uninstalling on a Load-Balanced SystemUninstalling a load-balanced system requires removing the application files from each application server andthe Collaboration server. After running theUninstall option on one application server, that application server,the file system, and the database will be removed. Use theUninstall Appserver option to remove theapplication files on the Collaboration server and the other application servers.


9.1 S

P6 BETA D

RAFT







About the Installation Process > Uninstalling Blackboard Learn

How to Uninstall Blackboard Learn

IMPORTANT! If the uninstall procedure fails, contact Blackboard Technical Support by logging in toBehind the Blackboard at https://behind.blackboard.com.

Follow these instructions to fully uninstall Blackboard Learn.

1. Stop all Blackboard Learn services.2. Launch the Installer. Windows users can double-click the Installer. UNIX users should run the

following command to launch the Installer, where /usr/local/bbinstaller/java is thelocation of the installer file:/usr/local/bbinstaller/java –jar updater_file

3. After reading the welcomemessage, click Next or press ENTER to continue.4. To specify the directory where Blackboard is located, click Next to accept the default, or enter a

new value and then click Next. If Blackboard Learn is not found in the directory provided, theUpdater will attempt to install at the given location.

5. Select theUninstall Blackboard Learn option and click Next.6. A message displays explaining what will be uninstalled. Click Next to uninstall.


9.1 S

P6 BETA D

RAFT


Upgrades > About Upgrading to Release 9.1

Upgrades

About Upgrading to Release 9.1

Prepare for the UpgradeTo prepare for your upgrade, read the Understanding the Change information relevant to your current installationas well as the Release Notes for the release that you are installing and any subsequent Service Packs. Thesedocuments contain important information such as what's new and changed, prerequisites for the upgrade, andinstructions for running the Updater.

To learnmore about themethodologies for determining the Dell or Sun hardware needed to support BlackboardLearn, see About Hardware Sizing in a Dell Environment or About Hardware Sizing in a SunMicrosystemsEnvironment.

Perform the UpgradeFor steps to upgrade to Blackboard Learn Release 9.1, see the appropriate Upgrading section of this helpproject.

For steps to perform a fresh install of Blackboard Learn Release 9.1, see About the Installation Process.

After the UpgradeFor information about improve the performance of a Blackboard Learn deployment, see About OptimizingBlackboard Learn.

For information about the back-end administration of Blackboard Learn, including how to integrate with anexisting authentication system, see theManaging Servers section of this help project.

Understanding the Change in Release 9.1If upgrading from a previous product release or from a legacy product such as CE 8, the “Understanding theChange” document for each product release gives users a comprehensive look at the features and functions ofthis release and how they compare to the user’s current product release. Quick Reference documents are alsoavailable for Instructors and Administrators moving from CE 4, CE 8, or Vista 8.

These documents are available on the Blackboard Upgrade Center or Behind the Blackboard.

Blackboard LearnUnderstanding the Change from Learn 9.0

Blackboard Learn 9.1 Service Pack 1: Enhancements

Blackboard Learn 9.1 Service Pack 1: Enhancements in Outcomes Assessments

Academic SuiteUnderstanding the Change from Academic Suite


9.1 S

P6 BETA D

RAFT






































Upgrades > Running the Pre-Update Change Report


Understanding the Change from CE 4 - Quick Reference for Administrators

Understanding the Change from CE 4 - Quick Reference for Instructors




Vista 8Understanding the Change from Vista 8



Running the Pre-Update Change ReportThe Pre-Update Change Report reviews the currently installed system to ensure that it meets the requirementsfor the upgrade. It then reports its findings and a list of all the file changes that will occur when the Installer isrun.

How to Run the Pre-Update Change Report on Windows1. Double-click the Installer. Alternatively, open a command line prompt and navigate to the directory

that contains the Installer.2. Run the following command to launch the Installer graphical interface:

C:\bb_installer>java –jar installer_file

Alternatively, run the following command to launch the Installer command line interface:

C:\bb_installer>java –jar installer_file -text


3. After reading the welcomemessage, press ENTER to continue.4. The first page asks where the Blackboard Installation Directory is found. Click Next to accept the

defaults or provide new values and then click Next. If Blackboard Learn is not found in the directoryprovided, the Installer will attempt to install at the given location.

5. On the next page, select Pre-Update Change Report and click Next.The update-report.log file will appear in the Installer directory. This file includes importantinformation about what changes will occur when the Installer is run.

How to Run the Pre-Update Change Report on UNIX


9.1 S

P6 BETA D

RAFT

























































Upgrades > Release 9.0 to 9.1

1. Open a command-line prompt and navigate to the directory that contains the Installer.2. Execute the root user login profile:

./su -root

3. Run the following command to launch the Installer:$JAVA_HOME/java –jar installer_file

4. After reading the welcomemessage, press ENTER to continue.5. The first page asks where the Blackboard Installation Directory is found. Press ENTER to accept

the defaults or provide new values and then click Next. If Blackboard Learn is not found in thedirectory provided, the Installer will attempt to install at the given location.

6. At the next prompt, select Pre-Update Change Report and click Next.The update-report.log file will appear in the Installer directory. This file includes importantinformation on what changes will occur when the Installer is run.

Release 9.0 to 9.1

Windows

Preparing for the Upgrade on WindowsBefore running the Blackboard Learn Updater, address the following considerations:

BackupsCreate a backup of the system and then verify that the current backup and restoration procedure will besuccessful.

CustomizationsRunning the Updater on an existing system will reset many back-end and user interface customizations.

Examples of affected back-end settings include:

l JAVA_HOME system environment variable

l SSL and custom authentication settings

l Settings in the bb-config.properties, authentication.properties, andwrapper.conf files

Examples of affected user interface settings include:

l Course Settings (which control the Coursemenu)

l Building Block availability

l Module and Tab availability, role settings, and custom layouts

IMPORTANT! Customizations will need to be reapplied after the upgrade. Tomake this process easier,create a detailed document outlining all existing customizations. Any configuration files removed by theupgrade will be placed in the blackboard_home/backups/upgrade_timestamp directory. Use thesefiles as a guide when updating the new configuration files to reapply your previous customizations.


9.1 S

P6 BETA D

RAFT


Upgrade PathsConfirm that you are running a version of Blackboard Learn that can be upgraded directly to Blackboard LearnRelease 9.1. This information is available in "Supported Technologies" in the Release Notes for the release thatyou are installing.

Server and Database ConfigurationsConfirm that Blackboard supports your current server and database configuration. This information is availablein "Supported Technologies" in the Release Notes for the release that you are installing.

License FilesContact Blackboard Client Operations though the Upgrade Center to request a new license key file (bb-license.xml) for Blackboard Learn Release 9.1. Make sure to do so well in advance of the upgrade. It isimportant to obtain a new license file to ensure the upgrade includes new features and functions. Save the newlicense file in the same directory as the updater. Be sure not to confuse the new license with the old license file.

Tomcat Cluster NodesIf installed, uninstall all Tomcat cluster nodes. To learnmore, see Set Up a Clustered Tomcat Environment onWindows in a Load-Balanced Configuration.

Custom AuthenticationTurn off custom authentication. To learnmore, seehttp://kb.blackboard.com/display/KB/Custom+Authentication.

.NET APIs and Building BlocksSupport for .NET APIs and .NET Building Blocks has been removed from Blackboard Learn in Release 9.1. If you are using .NET APIs and Building Blocks, they will not work in Release 9.1. Replace them withcomparableWeb Services and Java Building Block APIs. To learnmore about the available APIs, go tohttp://www.edugarage.com.

Content Management SettingsThis section applies only to schools that license content management.

If your school licenses content management, the /courses top level content directory must be available sothat Release 9.1 has an initial default directory for content. If your school licenses community engagement, the/organizations top level content directory must also be available. If these directories are not available, theinstallation will fail.

How to Change the Content Management Availability Settings1. Log in as an administrator to Blackboard Release 9.2. On the Administrator Panel, underContent Management, click Content Area Management, and

then click Content Area Availability.3. Under /courses Content Area, ensure that Allow Add Content is set toYes.4. If your school also licenses community engagement, under /organizations Content Area, ensure

that Allow Add Content is set toYes.5. Click Submit.


9.1 S

P6 BETA D

RAFT





http://www.blackboard.com/Sites/UpgradeCenter/testpilot.aspx


http://kb.blackboard.com/display/KB/Custom+Authentication

http://www.edugarage.com/


After the UpgradeLeaving the /courses and /organizations directories available after the upgrade provides courses andorganizations with a customizable home folder. These home folders retain a course’s or organization's contentso that it is archived with the course or organization. They also allow the course or organization to point to othershared content outside of the home folder, which is not archived with the course or organization.

In Release 9 and earlier versions, shared content had to bemaintained in some location other than the defaultdirectories to prevent that content from being removed during a course or organization archive. Institutionsworked around this by turning off the /courses and /organizations top level directories. Many institutionswill now want to continue to store shared content in a subdirectory of the /institution area but leave the/courses and /organizations areas available for supplemental attachments that are relevant to thecourse or organization offering. Improvements to archive, export, and copy in Release 9.1 enable your school tochoose to archive the entire course or organization with the linked files (for archival purposes) or only thereference links (for reuse purposes).

Database TasksVerify that database tasks, such as backups, indexing, and statistics gathering, are not running when you beginthe upgrade.

Application Server Batch JobsVerify that no batch jobs, such as those initiated by Snapshot commands, are running on the application serverwhen you begin the upgrade.

SQL Server AgentVerify that the SQL Server Agent is running during the upgrade and while Blackboard Learn is in production.From the Control Panel, openAdministrative Tools and thenServices to verify that the SQL Server Agentservice has a status of Started.

UtilitiesBlackboard strongly recommends turning off various utilities that may conflict with the upgrade process, suchas virus scanners and backup utilities. Failure to do somay cause the Upgrade to fail and leave the database inan indeterminate state because the Installer will be attempting tomodify an object that is in use.

Firewall PortsEnsure that your firewall has the necessary external ports open so that the upgrade and application will work onyour network. The following table lists the parameters in the bb-config.properties file for the necessaryports and their default settings.

Parameter Default Port Open between

bbconfig.webserver.portnumber 80 All

bbconfig.collabserver.portnumber.tcp.default 8010 All

bbconfig.collabserver.portnumber.http.default 8011 All

bbconfig.collabserver.portnumber.ssl.default 8443 All

bbconfig.database.server.portnumber 1433 Application and database only

Upgrading a Load-Balanced SystemOn a load-balanced system, the Updater must be run on each Application server in sequential order.


9.1 S

P6 BETA D

RAFT


Note: The Collaboration server can reside on an existing, dual-purposed application server in the load-balanced environment. If the Collaboration server resides on a separate server, the Updater alsomust be run onthe Collaboration server.

After running the Updater for the first time using the instructions in the following section, run the Updater againon each Application Server (and on the Collaboration Server if applicable) using theUpgrade appserver onlyoption in the Updater. TheUpgrade appserver only option upgrades the application files without making anyof the database changes. Because theUpgrade appserver only option does not access the database, nodescan be added to a load-balanced system while the system is live.

In Tomcat clustered environments, cross-server communication is needed to synchronize caches acrossmultiple application servers. All Blackboard Learn systems spanningmultiple application servers must be partof the same ServerGroup and communicate using the port specified in that ServerGroup. Each node requires itsown unique ServerGroup and associated port number. For more information, see (Optional) Set Up a ClusteredTomcat Environment onWindows in a Load-Balanced Configuration or (Optional) Set Up a Clustered TomcatEnvironment on UNIX in a Load-Balanced Configuration.

Running the Updater on Windows

WARNING! Running the Updater on an existing system will reset many back-end and user interfacecustomizations. Customizations will need to be reapplied after the upgrade. To learnmore, seeCustomizations.

Follow these steps to run the Updater:

1. Make sure that the JAVA_HOME system environment variable points to a full Java SDK, version1.6.x. The path cannot contain spaces. For example: C:\JDK6

2. Place the Updater file in the desired location, and then double-click the Updater file to launch theUpdater.

3. Click Next to continue.4. Confirm the installation and content directories for your environment, and then click Next. Load-

balanced systems should use the correct UNC path for your content directory.5. At the next prompt, select Provide new license file, and then click Next. TheProvide new

license file option updates the system and applies the new license file that you obtained.6. When amessage appears displaying the changes that will bemade when the Updater runs,

carefully verify the changes. You will not be able to undo the changes after you start the upgrade.7. Click Next to start the upgrade.

WARNING! If you launched the Updater from the command line, do not close the command line windowduring the upgrade as it will cause the Upgrade to fail andmay leave the database in an indeterminate state.

IMPORTANT! To ensure that adaptive release rules are functioning correctly, courses created prior toBlackboard Learn Service Pack 6 need to be copied, imported, or restored after upgrading. This processupdates all links to content within a course and removes specific read permissions from students. Updatingthe links provides students with access to all files they had previously been granted access to. Removingspecific read permissions prevents students from accessing content that they are not allowed see whilehonoring adaptive release rules.


9.1 S

P6 BETA D

RAFT


Troubleshooting on WindowsThe Updater logs are an important source of information when troubleshooting issues that occur during anupgrade. The Updater writes to the following log:

\blackboard_home\logs\bb-installer-log.txt

If the installer log file does not identify the problem, the update-tool-log.txt file most likely contains thecause of any errors:

\blackboard_home\logs\update-tools\update-tool-log.txt

Also check the following install error and info logs in the following folder:

\blackboard_home\logs\install

l db-install-errors-log.txt

l db-install-errors-log_admin.txt

l db-install-errors-log_stats.txt

l db-install-errors-log-sys.txt

l db-install-info-log-sys.txt

l db-install-info-log.txt

l db-install-info-log_admin.txt

l db-install-info-log_stats.txt

Identifying Language Pack ChangesDuring the upgrade process, the existing en_US Language Pack is compared against the en_US LanguagePack from the updated version being installed. This automated step is included to promote consistency acrossreleases.

The en_US Language Pack differences are output to the following file:

blackboard_home\backups\upgrade_timestamp\bundle_diff.txt

Review this file to see the changes between releases and use it as a reference for updating any existingcustom Language Packs in your environment.

(Optional) Performing a 32-bit to 64-bit Cross-Platform MigrationBlackboard Learn Release 9.1 is the first release to offer an entire application and database footprint using 64-bit addressablememory. To take advantage of more addressablememory, Blackboard strongly encouragesclients to deploy using 64-bit operating systems (OSs) and sub components (Java and SQL Server or Oracle).Migrating to 64-bit operating systems allows institutions to deploy a 64-bit JVM with larger heap sizes thatsuppresses the need to run in Tomcat clustered environments.

Upgrading Blackboard Academic Suite 8.0 or Blackboard Learn 9.0 on existing hardware to Blackboard Learn9.1must occur beforemigration. Database restore to a 64-bit machinemust be completed before running theapplication server upgrade.

WindowsFor information about migrating a Blackboard Learn 9.1 instance operating on aWindows 32-bit platform toBlackboard Learn 9.1 operating on aWindows 64-bit platform, see 32-bit to 64-bit Cross Platform Migration forWindows.


9.1 S

P6 BETA D

RAFT

http://library.blackboard.com/d?5ef5ca4b-a0d3-42d3-b6af-ba054c478416











UNIXFor information about migrating a Blackboard Learn 9.1 instance operating on a UNIX 32-bit platform toBlackboard Learn 9.1 operating on a UNIX 64-bit platform, see 32-bit to 64-bit Cross Platform Migration forUNIX.

UNIX

Preparing for the Upgrade on UNIXBefore running the Blackboard Learn Updater, address the following considerations:










IMPORTANT! Customizations will need to be reapplied after the upgrade. Tomake this process easier,create a detailed document outlining all existing customizations. Any configuration files removed by theupgrade will be placed in the blackboard_home/backups/upgrade_timestamp directory. Usethese files as a guide when updating the new configuration files to reapply your previous customizations.

Upgrade PathsConfirm that you are running a version of Blackboard Learn that can be upgraded directly to Blackboard LearnRelease 9.1. This information is available in "Supported Technologies" in the Release Notes for the release thatyou are installing.

Server and Database ConfigurationsConfirm that Blackboard supports your current server and database configuration. This information is availablein "Supported Technologies" in the Release Notes for the release that you are installing.

License FilesContact Blackboard Client Operations though the Upgrade Center to request a new license key file (bb-license.xml) for Blackboard Learn Release 9.1. Make sure to do so well in advance of the upgrade. It is


9.1 S

P6 BETA D

RAFT

http://library.blackboard.com/d?08f4b24b-a369-4bfe-96d5-aa42b1f109b7

















important to obtain a new license file to ensure the upgrade includes new features and functions. Save the newlicense file in the same directory as the updater. Be sure not to confuse the new license with the old license file.

Tomcat Cluster NodesIf installed, uninstall all Tomcat cluster nodes. To learnmore, see Set Up a Clustered Tomcat Environment onUNIX in a Load-Balanced Configuration.


Content Management SettingsThis section applies only to schools that license content management.


How to Change the Content Management Availability Settings1. Log in as an administrator to Blackboard Release 9.2. On the Administrator Panel, underContent Management, click Content Area Management, and

then click Content Area Availability.3. Under /courses Content Area, ensure that Allow Add Content is set toYes.4. If your school also licenses community engagement, under /organizations Content Area, ensure






9.1 S

P6 BETA D

RAFT



Application Server Batch JobsVerify that that no batch jobs, such as those initiated by Snapshot commands, are running on the applicationserver when you begin the upgrade.



Parameter Default Port Open for





bbconfig.database.bbadmin.machine.portnumber 1521 Application and database only

Solaris Users Only: Swap SpaceIf running on Solaris, ensure that the Swap space for the operating system is 0.5 – 1.5 times the amount ofphysical RAM on the server. To learnmore, see http://www.sun.com/bigadmin/content/submitted/swap_space_impact.jsp.






9.1 S

P6 BETA D

RAFT

http://www.sun.com/bigadmin/content/submitted/swap_space_impact.jsp




Running the Updater on UNIX


How to Run the Updater on UNIX1. Place the Updater file in the desired location.2. Login as root.3. From the command line, navigate to the location of the Updater.4. Issue the following command to run the Updater:

$JAVA_HOME/bin/java -jar updater_filename

If using the X Windows System (X11) or a similar GUI solution and the DISPLAY variable isproperly configured, the Updater will launch in GUI mode.

Note: The following steps assume that the command line Updater is used.

5. Press ENTER to continue. Follow the prompts.6. Confirm the installation and content directories for your environment, and then press ENTER. If the

Blackboard Learn installation is not found in the path provided, the Updater attempts to install inthis location.

7. At the next prompt, select theProvide new license file option, and then press ENTER. TheProvide new license file option updates the system and applies the new license file that youobtained.

8. When amessage appears displaying the changes that will bemade when the Updater runs,carefully verify the changes. You will not be able to undo the changes after you start the upgrade.

9. Click Next to start the upgrade.

WARNING! Do not close the command line window during the upgrade as it will cause the Upgrade to failandmay leave the database in an indeterminate state.

IMPORTANT! To ensure that adaptive release rules are functioning correctly, courses created prior toBlackboard Learn Service Pack 6 need to be copied, imported, or restored after upgrading. This processupdates all links to content within a course and removes specific read permissions from students. Updatingthe links provides students with access to all files they had previously been granted access to. Removingspecific read permissions prevents students from accessing content that they are not allowed see whilehonoring adaptive release rules.

Troubleshooting on UNIXThe Updater logs are an important source of information when troubleshooting issues that arise during anupgrade. The Updater writes to the following log:

/blackboard/logs/bb-installer-log.txt


/blackboard/logs/update-tools/update-tool-log.txt


9.1 S

P6 BETA D

RAFT



/blackboard_home/logs/install










The en_US Language Pack differences are output to the following file:








9.1 S

P6 BETA D

RAFT





















Upgrades > Release 8 to 9.1

Release 8 to 9.1

Windows

Preparing for the Upgrade on WindowsBefore running the Blackboard Learn Updater, address the following considerations:




l JAVA_HOME system environment variable







IMPORTANT! Customizations will need to be reapplied after the upgrade. Tomake this process easier,create a detailed document outlining all existing customizations. Any configuration files removed by theupgrade will be placed in the blackboard_directory/backups/upgrade_timestamp directory.Use these files as a guide when updating the new configuration files to reapply your previouscustomizations.

Upgrade PathsConfirm that you are running a version of Academic Suite that can be upgraded directly to Blackboard LearnRelease 9.1. The information for the release of 9.1 that you are installing is available in "SupportedTechnologies" in the Release Notes for the release that you are installing.

Server and Database ConfigurationsConfirm that Blackboard supports your current server and database configuration. The information for theversion of 9.1 that you are installing is available in "Supported Technologies" in the Release Notes for therelease that you are installing.


9.1 S

P6 BETA D

RAFT







Tomcat Cluster NodesIf installed, uninstall all Tomcat cluster nodes. To learnmore, see Set Up a Clustered Tomcat Environment onWindows in a Load-Balanced Configuration.


.NET APIs and Building BlocksSupport for .NET APIs and .NET Building Blocks has been removed from Blackboard Learn in Release 9.1. If you are using .NET APIs and Building Blocks, they will not work in Release 9.1. Replace them withcomparableWeb Services and Java Building Block APIs. To learnmore about the available APIs, go tohttp://www.edugarage.com.

Content Management SettingsThis section applies only to schools that license content management (previously known as the ContentSystem).


How to Change the Content Management Availability Settings1. Log in as an administrator to Blackboard Release 8.2. On the Administrator Panel, underBlackboard Content System, click Settings, and then click

Content Area Availability.3. Under /courses Content Area, ensure that Allow Add Content is set toYes.4. If your school also licenses community engagement, under /organizations Content Area, ensure



In Release 9 and earlier versions, shared content had to bemaintained in some location other than the defaultdirectories to prevent that content from being removed during a course or organization archive. Institutionsworked around this by turning off the /courses and /organizations top level directories. Many institutionswill now want to continue to store shared content in a subdirectory of the /institution area but leave the


9.1 S

P6 BETA D

RAFT






/courses and /organizations areas available for supplemental attachments that are relevant to thecourse or organization offering. Improvements to archive, export, and copy in Release 9.1 enable your school tochoose to archive the entire course or organization with the linked files (for archival purposes) or only thereference links (for reuse purposes).



SQL Server AgentVerify that the SQL Server Agent is running during the upgrade and while Blackboard Learn is in production.From the Control Panel, openAdministrative Tools and thenServices to verify that the SQL Server Agentservice has a status of Started.



Parameter Default Port Open between





bbconfig.database.server.portnumber 1433 Application and database only





9.1 S

P6 BETA D

RAFT



Running the Updater on Windows


How to Run the Updater on Windows1. Make sure that the JAVA_HOME system environment variable points to a full Java SDK, version

1.6.x. The path cannot contain spaces. For example:C:\JDK6

2. Place the Updater file in the desired location, and then double-click the Updater file to launch theUpdater.

3. Click Next to continue.4. Confirm the installation and content directories for your environment, and then click Next. Load-

balanced systems should use the correct UNC path for your content directory.5. At the next prompt, select Provide new license file, and then click Next. TheProvide new

license file option updates the system and applies the new license file that you obtained.6. When amessage appears displaying the changes that will bemade when the Updater runs,

carefully verify the changes. You will not be able to undo the changes after you start the upgrade.7. Click Next to start the upgrade.

WARNING! If you launched the Updater from the command line, do not close the command line windowduring the upgrade as it will cause the Upgrade to fail andmay leave the database in an indeterminate state.

Troubleshooting on WindowsThe Updater logs are an important source of information when troubleshooting issues that occur during anupgrade. The Updater writes to the following log:

\blackboard_directory\logs\bb-installer-log.txt


\blackboard_directory\logs\update-tools\update-tool-log.txt


\blackboard_directory\logs\install





9.1 S

P6 BETA D

RAFT








The en_US language pack differences are output to the following file:







UNIX

Preparing for the Upgrade on UNIXBefore running the Blackboard Learn Updater, address the following considerations:



9.1 S

P6 BETA D

RAFT






























IMPORTANT! Customizations will need to be reapplied after the upgrade. Tomake this process easier,create a detailed document outlining all existing customizations. Any configuration files removed by theupgrade will be placed in the blackboard_home/backups/upgrade_timestamp directory. Usethese files as a guide when updating the new configuration files to reapply your previous customizations.

Upgrade PathsConfirm that you are running a version of Academic Suite that can be upgraded directly to Blackboard LearnRelease 9.1. The information for the release of 9.1 that you are installing is available in "SupportedTechnologies" in the Release Notes for the release that you are installing.

Server and Database ConfigurationsConfirm that Blackboard supports your current server and database configuration. The information for theversion of 9.1 that you are installing is available in "Supported Technologies" in the Release Notes for therelease that you are installing.


Tomcat Cluster NodesIf installed, uninstall all Tomcat cluster nodes. To learnmore, see Set Up a Clustered Tomcat Environment onUNIX in a Load-Balanced Configuration.


Content Management SettingsThis section applies only to schools that license content management (previously known as the ContentSystem).


9.1 S

P6 BETA D

RAFT










How to Change the Content Management Availability Settings1. Log in as an administrator to Blackboard Release 8.2. On the Administrator Panel, underBlackboard Content System, click Settings, and then click

Content Area Availability.3. Under /courses Content Area, ensure that Allow Add Content is set toYes.4. If your school also licenses community engagement, under /organizations Content Area, ensure








Parameter Default Port Open for


9.1 S

P6 BETA D

RAFT






bbconfig.database.bbadmin.machine.portnumber 1521 Application and database only

Solaris Users Only: Swap SpaceIf running on Solaris, ensure that the Swap space for the operating system is 0.5 – 1.5 times the amount ofphysical RAM on the server. To learnmore, see http://www.sun.com/bigadmin/content/submitted/swap_space_impact.jsp.





Running the Updater on UNIX


How to Run the Updater on UNIX1. Place the Updater file in the desired location.2. Login as root.3. From the command line, navigate to the location of the Updater.4. Issue the following command to run the Updater:

$JAVA_HOME/bin/java -jar updater_filename

If using the X Windows System (X11) or a similar GUI solution and the DISPLAY variable isproperly configured, the Updater will launch in GUI mode.

Note: The following steps assume that the command line Updater is used.

5. Press ENTER to continue. Follow the prompts.


9.1 S

P6 BETA D

RAFT





6. Confirm the installation and content directories for your environment, and then press ENTER. If theAcademic Suite installation is not found in the path provided, the Updater attempts to install in thislocation.

7. At the next prompt, select theProvide new license file option, and then press ENTER. TheProvide new license file option updates the system and applies the new license file that youobtained.

8. When amessage appears displaying the changes that will bemade when the Updater runs,carefully verify the changes. You will not be able to undo the changes after you start the upgrade.

9. Click Next to start the upgrade.

WARNING! Do not close the command line window during the upgrade as it will cause the Upgrade to failandmay leave the database in an indeterminate state.

Troubleshooting on UNIXThe Updater logs are an important source of information when troubleshooting issues that arise during anupgrade. The Updater writes to the following log:

/blackboard_home/logs/bb-installer-log.txt


/blackboard_home/logs/update-tools/update-tool-log.txt


/blackboard_home/logs/install










The en_US language pack differences are output to the following file:




9.1 S

P6 BETA D

RAFT

Upgrades > CE 4 to Learn 9.1





CE 4 to Learn 9.1

Before You Begin

Things to ConsiderThe following are things to consider before starting the upgrade process:

l Invest in a test server or consider moving to BlackboardManaged Hosting. Upgrading to BlackboardLearn is a complex process and should be approached as such. Blackboard strongly encourages allclients to have at least one test system.

Note: Basic Edition clients will need to purchase a test license or upgrade to an Enterprise Editionlicense.

l Consider whether to implement Blackboard Learn in a virtualized environment. To learnmore, seeVirtualizing the Blackboard Reference Architecture available on Behind the Blackboard.

l Passwords will not be imported into Blackboard Learn. Administrators must reset the user passwordsbefore the users will be able to log in to Blackboard Learn.

l Customized PowerLinks will not bemoved to Blackboard Learn. To learnmore, see the Proxy Toolsdocumentation available on www.edugarage.com.

Things to DoThe following are tasks that youmust complete before starting the upgrade process:

l Install CE 4.1.7.l Back up all data and store copies of the backup files on a local machine or drive.


9.1 S

P6 BETA D

RAFT


























l Confirm that Blackboard supports your server and database configuration. This information isavailable in "Supported Technologies" in the Release Notes for the release that you are installing.

l To reduce the amount of time it takes to complete the upgrade, clean up old course on the CE 4server.

l Enterprise Edition clients only: Create a unique Data Source Key to identify the data imported fromCE 4. To learnmore, see Data Source Keys.

Understanding the ProcessSignificant planning and preparation is necessary to upgrade all courses to Blackboard Learn successfully. Thesteps involved depend on licensing, hardware, existing Blackboard systems, and institutional policies andprocedures.

Users and courses aremoved from CE 4 to Blackboard Learn using various export and import operations.Upgrading from CE 4 to Blackboard Learn involves the following steps:

Step 1: Install Blackboard Learn on separate hardware.

Step 2: Export All Data from CE 4. This data will be used throughout the upgrade process.

Step 3: Import CE 4 User Data into Blackboard Learn.

Step 4: Export Course Content Packages from CE 4.

Step 5: Import CE 4 Courses into Blackboard Learn.

Step 6: Import CE 4 Enrollments into Blackboard Learn. If you have an SIS integration with Blackboard Learn orplan tomanage enrollments manually, you can skip this step.

During the upgrade process, you have a variety of choices that depend on your needs. It is important to decidewhen and what data you plan tomove.

After all courses have beenmoved and are active in Blackboard Learn, you can archive and then turn off thelegacy CE 4 system. All users will log into Blackboard Learn using a new password, and the legacy system willno longer need to be used or maintained.

Deciding When to UpgradeIt is important to decide how Blackboard Learn will be introduced to faculty and students. Blackboardrecommends moving courses between school terms tominimize disruptions.

If you host active courses 365 days per year, you will need to run both the Blackboard Learn system and thelegacy CE 4 system in productionmode while you complete your upgrade. Blackboard recommends that youmove all of your data to the Blackboard Learn system and then set the courses that are still being hosted in theproduction CE 4 system as Inactive in Blackboard Learn until the courses on CE 4 have ended. When the CE 4course ends, you can activate the course in Blackboard Learn.

Deciding Which Courses to MoveDepending on your needs, some faculty will want to upgrade their CE 4 course to Blackboard Learn while otherfaculty will want to build new courses in Blackboard Learn.

All of the CE 4 courses can be exported andmoved to Blackboard Learn, but youmay not want to export olderversions of the same course or other groups of courses. If you do not want to import a particular course, thecontent package for a course can be removed from themigrate directory before the import as described in Step 5: Import CE 4 Courses into Blackboard Learn. As a result, the course will be created in Blackboard Learn, butthe CE 4 content will not be imported.


9.1 S

P6 BETA D

RAFT




Assigning Data Source KeysWhen using Blackboard Learn - Enterprise Edition, all data that is moved to the Blackboard Learn database istagged with a data source identifier, called a data source key, so that the dataset can bemanaged using thesnapshot/bin tool. For example, youmay choose to identify all Fall 2008 records imported from CE 4withthe data source key “CE_FALL_2009” and all Spring 2010 records with the data source key “CE_SPRING_2010.”

Enterprise Edition clients should consider creating a data source key for each set of courses beingmoved.Blackboard recommends creating a data source key for each school term (or group of terms, if desired) andassigning that data source key to the appropriate courses during Step 5: Import CE 4 Courses into BlackboardLearn.

For steps to verify or create a data source key, see Data Source Keys. To learnmore about data source keysand the snapshot/bin tool, see About the Snapshot Tool.

Resolving Data ConflictsIf your Blackboard Learn system contains any pre-existing data, Blackboard strongly recommends using aconflict resolution switch when complete Step 3: Import CE 4 User Data into Blackboard Learn and Step 5:Import CE 4 Courses into Blackboard Learn. Without one of these switches, data collisions may cause theimport to fail. To learnmore, see LMSImport Switches for CE 4.

Including EnrollmentsWhen youmove your data, you can choose whether to include all enrollments or to include only instructorenrollments as described in Step 6: Import CE 4 Enrollments into Blackboard Learn. Your decision depends onwhether you have built an SIS integration against Blackboard Learn.

If you have an SIS integration, you do not need to import the enrollments into Blackboard Learn. The SISintegration will handle the new enrollments for upcoming school terms.

If you do not have an SIS integration and you will bemanually updating user enrollments in Blackboard Learn, itmay be easier for you to include these enrollments.

Step 1: Install Blackboard LearnInstall Blackboard Learn 9.1 on hardware separate from your CE 4 installation.

For steps to install Blackboard Learn, see Installing Blackboard Learn.

Step 2: Export All Data from CE 4All data from CE 4must be exported so that the appropriate data can be imported into Blackboard Learn. Thisprocess is completed using the System Integration API’s ep_api.pl command. The resultingsnapshot.xml file will be used in each of the import steps in the upgrade process.

Complete this procedure using the command line on the CE 4 server.

1. Log in to the CE 4 server with system administrator privileges.2. Create a directory for your migration data using the following command.

UNIX:

mkdir /tmp/migrateToLearn

Windows:


9.1 S

P6 BETA D

RAFT

../../../../../Content/Mini_TOCs/mt_admin_server_install.htm




mkdir c:\temp\migrateToLearn

3. Navigate to the ims directory using the following command.

UNIX:

cd /CE4_home/webct/webct/generic/ims

Windows:

cd \CE4_home\webct\webct\generic\ims

4. Export the CE 4 data to a snapshot.xml file using the following command.

UNIX:

./ep_api.pl export snapshot /tmp/migrateToLearn/snapshot.xml

Windows:

ep_api.pl export snapshot c:\temp\migrateToLearn\snapshot.xml

Step 3: Import CE 4 User Data into Blackboard LearnAll users from CE 4must added to the Blackboard Learn user database. This process is completed using theLMSImport command and the snapshot.xml file resulting from Step 2: Export All Data from CE 4.

Importing user data into Blackboard Learn from an existing system preserves user account data such as loginID, role, and so on, but user-related data such as passwords, quiz attempts, coursemembership information,group enrollment, and so on will not be included. For specific information about lost and retained data, refer toUnderstanding the Change from CE 4 to Blackboard Learn 9.1.

This procedure will create new users in Blackboard Learn, but it will not update any existing user information. Inother words, if a user with the same user_id already exists in Blackboard Learn, the user will not be updatedor merged. Depending on the switches used with the import command, Blackboard Learn can add a prefix orsuffix the user_id to distinguish between the two.

Note: Enterprise Edition clients only: Before you begin, make sure that you have created a data source key forthe user data being imported. To learnmore, see Assigning Data Source Keys.

Complete this procedure using the command line of the Blackboard Learn server.

1. Log in to the Blackboard Learn server with system administrator privileges.2. Create a directory for your migration data using the following command.

UNIX:

mkdir /tmp/migrateFromCE

Windows:

mkdir c:\temp\migrateFromCE

3. Copy the snapshot.xml file from the migrateToLearn directory on the CE 4 server to themigrateFromCE directory on the Blackboard Learn server.

4. Navigate to the admin directory using the following command.

UNIX:

cd /Learn_home/blackboard/tools/admin

Windows:

cd \Learn_home\blackboard\tools\admin


9.1 S

P6 BETA D

RAFT


5. Import the user data from the snapshot.xml file using the LMSImport command and theappropriate switches. To learnmore about the available switches, see LMSImport Switches for CE4.

Note: If you are a Basic Edition client, do not include the --ds=data source key switch.Basic Edition licenses do not support Data Source Key functionality.

Note: Parameters shown in brackets ([ ]) are optional.

Note: Use only one --conflict resolution switch in the command.

UNIX:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml--ds=data source key --no_courses --no_enrollments [--conflict_prefix prefix][--conflict_suffix suffix] [--always]

For example:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml--ds=CE_FALL_2009 --no_courses --no_enrollments --conflict_prefix CE_ --always

Windows:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml --ds=data source key --no_courses --no_enrollments [--conflict_prefix prefix] [--conflict_suffixsuffix] [--always]

For example:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml --ds=CE_FALL_2009 --no_courses --no_enrollments --conflict_prefix CE_ --always

A running count of the records processed displays. The bb-services-log-integration-jdbc.txt log file is created and stored in the Learn_home/blackboard/logs/snapshotdirectory on the Blackboard Learn server for users that fail to import.

Step 4: Export Course Content Packages from CE 4The content from the desired courses in CE 4must be exported as packages so that they can be imported intoBlackboard Learn. This process is completed using the System Integration API’s ./cp_api.pl command.The resulting packages will be used in Step 5: Import CE 4 Courses into Blackboard Learn.

WARNING! Exporting the content packages can be a very time-consuming process. Blackboardrecommends exporting subsets of your courses.

Complete this procedure using the command line on the CE 4 server.

1. Log in to the CE 4 server with system administrator privileges.2. Navigate to the ims directory using the following command.

UNIX:

cd /CE4_home/webct/webct/generic/ims

Windows:

cd \CE4_home\webct\webct\generic\ims

3. Create the content packages using the following command. To export the content of all of thecourses in CE 4, use --course=* as shown in the following example. To export specific courses,the wildcard (*) can be replaced with a colon-delimited list of courseids.

UNIX:


9.1 S

P6 BETA D

RAFT


./cp_api.pl --action=export_to_vista --course=* --pkgloc=/tmp/migrateToLearn/

Windows:

cp_api.pl --action=export_to_vista --course=* --pkgloc=c:\temp\migrateToLearn\

4. Copy the resulting content packages ( *zip and*.epk) from the migrateToLearn directory onthe CE 4 server to the migrateFromCE directory on the Blackboard Learn server.

Step 5: Import CE 4 Courses into Blackboard LearnThe import courses process is completed using the LMSImport command, the snapshot.xml file resultingfrom Step 2: Export All Data from CE 4, and the content packages resulting from Step 4: Export CourseContent Packages from CE 4.

If you do not want to import the content for a particular course, delete the content package for that course fromthe migrateFromCE directory before completing this procedure. The course will be created in BlackboardLearn, but the CE 4 content will not be imported.

Note: Enterprise Edition clients only: Before you begin, make sure that you have created a data source key forthe courses being imported. To learnmore, see Assigning Data Source Keys.

Complete this procedure using the command line on the Blackboard Learn server.

1. Log in to the Blackboard Learn server with system administrator privileges.2. Navigate to the admin directory using the following command.

UNIX:


Windows:


3. Import the course content from the snapshot.xml file and the content packages (*zip an*.epk) using the LMSImport command and the appropriate switches. For more information aboutthe available switches, see LMSImport Switches for CE 4.




UNIX:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml --ds=data source key --pkg_dir=/tmp/migrateFromCE --no_users --no_enrollments [--conflict_prefixprefix] [--conflict_suffix suffix] --always --i course material type

For example:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml--ds=CE_FALL_2009 --pkg_dir=/tmp/migrateFromCE --no_users --no_enrollments --conflict_prefix CE_ --always --i Alignments,Announcement,Assessment,Calendar

Windows:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml --ds=data source name --pkg_dir=c:\temp\migrateFromCE --no_users --no_enrollments [--conflict_prefixprefix] [--conflict_suffix suffix] --always --i course material type

For example:


9.1 S

P6 BETA D

RAFT


LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml--ds=CE_FALL_2009 --pkg_dir=c:\temp\migrateFromCE --no_users --no_enrollments --conflict_prefix CE_ --always --i Alignments,Announcement,Assessment,Calendar

After each package has been imported, amessage displays listing the time that it took to import thepackage contents.

After all of the packages have been imported, amessage displays indicating that all operations arecomplete and that a log file has been written to the following file:

UNIX:

/usr/local/blackboard/logs/content-exchange/batchcxcmd_checklog.txt

Windows:

c:\blackboard\logs\content-exchange\batchcxcmd_checklog.txt

Batch Import Courses Using an Alternative to the Snapshot ToolBlackboard Learn includes a tool for handling the import of a number of Courses at once as well as the import offiles that exceed the default maximum upload limit. This tool will process a batch file that includes the CourseID and the name. Accepted import file type extension is .EPK as generated by CE 4. When using a CE 4backup file, the IMS content export files with an .EPK extensionmust be used, the CE4 backup files with a.ZIP extension cannot be used.

How to Create an Import Batch FileA batch file used with the batch_ImportExport tool only has two values in each row, the Course ID and the fullpath to the backup package. When running an Import action, the specified path and file name point to thegenerated backup package associated with the destination Course ID.

The following are examples of the contents of a batch file for use with the batch_ImportExport tool. Files shouldbe saved as text (.txt) files.

Import ExamplesHIST101, C:\Course_archives\Archive_File_HIST101.epk

HIST301, C:\Course_archives\Archive_File_HIST301.epk


Import batch files require the exact path, including the name of the package.

How to Run the ToolThe Batch tool for running Import functions must be run from the command line. The tool must be run from theWeb/app server. The command syntax is shown below.

Windows Syntax:

C:\Blackboard\apps\content-exchange\bin\batch_ImportExport.bat –f path_to_file -ldelimiter -t import -n virtual_hostname

Note: Use cmd.exe to open a command line for running the tool. Running the tool from command.exe willresult in errors.

UNIX Syntax:

/usr/local/blackboard/apps/content-exchange/bin/batch_ImportExport.sh –f path_to_file -ldelimiter -t import -n virtual_hostname


9.1 S

P6 BETA D

RAFT


The exact path to the Blackboard directory may be different depending on where Blackboard Learn wasinstalled.

ArgumentDescription

path_to_file

Provide the full path to the batch file.

delimiter Provide one of the following values:l 1: Identifies comma (,) as the delimiter.l 2: Identifies semicolon (;) as the delimiter.l 3: Identifies TAB as the delimiter.

virtual_hostname

The name of the virtual installation that the tool will run against. If there are no Virtual Installations, or ifthis argument is not given, the tool will run against the default Virtual Installation.

How to Customize the JVM Heap Size for the batch_ImportExport Tool1. Open the batch_ImportExport.bat or batch_ImportExport.sh file for editing.2. Add an $OPTS or %OPTS parameter to include the customized JVM heap size. The syntax is shown

below. The following example uses a JVM Heap size of 6 GB, and should be changed tomeet therequirements of your institution.

Windows:

OPTS="%OPTS -Xmx6g"

UNIX:

OPTS="$OPTS -Xmx6g"

Step 6: Import CE 4 Enrollments into Blackboard LearnIf you have an SIS integration, you do not need to import the enrollments into Blackboard Learn. The SISintegration will handle the enrollments for upcoming school terms. You can skip this step.

If you do not have an SIS integration and you will bemanually updating user enrollments in Blackboard Learn, itmay be easier for you to import the enrollments information. You can choose whether to include all enrollmentsor to include only instructor enrollments.

The import enrollments process is completed using the LMSImport command and the snapshot.xml fileresulting from Step 2: Export All Data from CE 4.



UNIX:


Windows:


3. Import the enrollments from the snapshot.xml file using the LMSImport command and theappropriate switches. To learnmore about the available switches, see LMSImport Switches for CE4.

To import only instructor enrollment data, use the --instr_only switch.


9.1 S

P6 BETA D

RAFT




UNIX:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml --ds=data source key --no_users --no_courses [--instr_only]

For example:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml--ds=CE_FALL_2009 --no_users --no_courses

Windows:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml --ds=data source name --no_users --no_courses [--instr_only]

For example:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml--ds=CE_FALL_2009 --no_users --no_courses

After all of the enrollments have been imported, amessage displays indicating that all operationsare complete.

Data Source KeysWhen using Blackboard Learn - Enterprise Edition, all data that is moved to the Blackboard Learn database canbe tagged with a data source identifier, called a data source key, so that the dataset can bemanaged using thesnapshot/bin tool. For example, youmay choose to identify all Fall 2009 records imported from CE 4 usingthe data source key “CE_FALL_2009” and all Spring 2010 records using the data source key “CE_SPRING_2010.”

This course provides the steps to check for existing data source keys and to create a new data source key.

How to Check for Existing Data Source KeysThe administrator can check for the existence of a data source key using the command line of the BlackboardLearn server.

1. Log in to the Blackboard Learn server with system administrator privileges.2. Navigate to the snapshot\bin directory using the following command:

UNIX:

cd /usr/local/blackboard/apps/snapshot/bin

Windows:

cd \blackboard\apps\snapshot\bin

3. List all existing data source keys using the following command.

UNIX:

./dsm.sh –f LIST

Windows:

dsm.cmd –f LIST


9.1 S

P6 BETA D

RAFT


How to Create a Data Source KeyThe administrator can create a new data source key using the command line of the Blackboard Learn server.Data source keys are created using the Data SourceManagement Tool.

1. Log in to the Blackboard Learn server with system administrator privileges.2. Navigate to the snapshot\bin directory using the following command.

UNIX:


Windows:

cd c:\blackboard\apps\snapshot\bin

3. Create the new data source key using the following command.

Note: The data source key can contain only letters, numbers, and underscores.The data source key cannot contain spaces.

UNIX:

./dsm.sh –f CREATE –b data source key -d "description"

For example:

./dsm.sh –f CREATE –b CE_FALL_2009 –d "All Fall 2009 Sections from CE migrationto Learn"

Windows:

dsm.cmd –f CREATE –b data source key -d "description"

For example:

dsm.cmd –f CREATE –b CE_FALL_2009 –d "All Fall 2009 Sections from CE migrationto Learn"

LMSImport Switches for CE 4The following table describes the available switches for the LMSImport command.

Switch Description

--file fullpath and nameof the datafile

Required in all LMSImport commands.

The full path to and the name of the file (snapshot.xml) that contains the data exported fromCE 4 in Step 2: Export All Data from CE 4.

--pkg_dir dirfull path topackages

Required in Step 5: Import CE 4 Courses into Blackboard Learn.

The full path to the directory where the course content packages (*.zip and *.epk) weresaved in Step 4: Export Course Content Packages from CE 4.

--dsDataSourceKey

Available only for Enterprise License clients.

Optional in Step 3: Import CE 4 User Data into Blackboard Learn, Step 5: Import CE 4 Coursesinto Blackboard Learn, and Step 6: Import CE 4 Enrollments into Blackboard Learn.

The data source key to be applied to the imported data. The data source key must already existon the system to be used in the command. To learn more, see Data Source Keys.

--no_courses Required in Step 3: Import CE 4 User Data into Blackboard Learn and Step 6: Import CE 4Enrollments into Blackboard Learn.

Do not import the available course shells.


9.1 S

P6 BETA D

RAFT


--no_enrollments

Required inStep 3: Import CE 4 User Data into Blackboard Learn and Step 5: Import CE 4Courses into Blackboard Learn.

Do not import the available user enrollment data. This switch is superseded by the --no_users and --no_courses switches.

--no_users Required in Step 5: Import CE 4 Courses into Blackboard Learn and Step 6: Import CE 4Enrollments into Blackboard Learn.

Do not import the available user records.

--no_content Optional. Import the course shells, but do not import the available content. This switch issuperseded by the --no_courses switch. The --pkg_dir switch is not effective when usedwith this switch.

--no_xlist Optional in Step 5: Import CE 4 Courses into Blackboard Learn.

Do not import the available cross-listed data. This switch is superseded by the --no_coursesswitch.

The import automatically copies parent content into the child courses. Both parent and childcourses will contain only their direct enrollments.

--instr_only Optional in Step 6: Import CE 4 Enrollments into Blackboard Learn.

Import only instructor enrollment data. This switch is superseded by the --no_enrollmentsswitch.

--conflict_prefix prefix

Optional in all LMSImport commands.

Resolve conflicting data names by attaching the included text string to the beginning of theimported data.

The prefix can contain only letters, numbers, and underscores. The prefix cannot containspaces.

You can use only one conflict resolution switch in the command. If you use the --conflict_prefix switch, do not use the --conflict_suffix switch.

--conflict_suffix suffix


Resolve conflicting data names by attaching the included text string to the end of the importeddata.

The suffix can contain only letters, numbers, and underscores. The suffix cannot containspaces.

You can use only one conflict resolution switch in the command. If you use the --conflict_suffix switch, do not use the --conflict_prefix switch.

--always Optional in all LMSImport commands when using either conflict resolution switch.

Always attach the conflict prefix or suffix to the imported data.

This switch requires either the --conflict_prefix or --conflict_suffix switch.

--i coursematerial type


Available course material types: Alignments, Announcement, Assessment, Calendar,Collaboration, Content, Coursesetting, Coursetoc, Discussion, Glossary, Gradebook, Group,Notification_rule, Pool, Staffinformation, Survey, Task, Blog, Journal, Availability_rule.

The course material types are not case sensitive, and must be comma-delimited if more thanone type is selected.


9.1 S

P6 BETA D

RAFT


CE 8 to Learn 9.1

Before You Begin




l Consider whether to implement Blackboard Learn in a virtualized environment. To learnmore, seeVirtualizing the Blackboard Reference Architecture available on Behind the Blackboard.




l Install themost recent CE 8 Service Pack.

Note: Blackboard recommends that MS SQL clients use CE 8.0.4.

l Back up all data and store copies of the backup files on a local machine or drive.l Confirm that Blackboard supports your server and database configuration. This information is

available in "Supported Technologies" in the Release Notes for the release that you are installing.l To reduce the amount of time it takes to complete the upgrade, clean up old sections on the CE 8

server.l Enterprise Edition clients only: Create a unique Data Source Key to identify the data imported from

CE 8. To learnmore, see Data Source Keys.

Understanding the ProcessSignificant planning and preparation is necessary to upgrade all sections to Blackboard Learn coursessuccessfully. The steps involved depend on licensing, hardware, existing Blackboard systems, andinstitutional policies and procedures.

Users and sections aremoved from CE 8 to Blackboard Learn using various export and import operations.Upgrading from CE 8 to Blackboard Learn involves the following steps:


Step 2: Export All Data from CE 8. This data will be used throughout the upgrade process.

Step 3: Import CE 8 User Data into Blackboard Learn.

Step 4: Export Section Content Packages from CE 8.

Step 5: Import CE 8 Sections into Blackboard Learn as Courses.


9.1 S

P6 BETA D

RAFT








Step 6: Import CE 8 Enrollments into Blackboard Learn . If you have an SIS integration with Blackboard Learnor plan tomanage enrollments manually, you can skip this step.

During the upgrade process, you have a variety of choices that depend on your institution’s needs. It isimportant to decide when and what data you plan tomove.

After all sections have beenmoved and are active in Blackboard Learn, you can archive and then turn off thelegacy CE 8 system. All users in the institution will log into Blackboard Learn using a new password, and thelegacy system will no longer need to be used or maintained.

Deciding When to UpgradeIt is important to decide how Blackboard Learn will be introduced to faculty and students. Blackboardrecommends moving courses between terms tominimize disruptions.

If your institution hosts active sections 365 days per year, you will need to run both the Blackboard Learnsystem and the legacy CE 8 system in productionmode while you complete your upgrade. Blackboardrecommends that youmove all of your data to the Blackboard Learn system and then set the courses that arestill being hosted in the production CE 8 system as Inactive in Blackboard Learn until the sections on CE 8have ended. When the section ends, you can activate the course in Blackboard Learn.

Deciding Which Sections to MoveAll of the CE 8 sections can be exported andmoved to Blackboard Learn as courses, but youmay not want toexport older versions of the same section or other groups of sections. Thebackup_request.xml file,described in Step 4: Export Section Content Packages from CE 8, can be edited to specify which sections toexport.

Depending on your institution’s needs, some faculty will want to upgrade their CE 8 section to BlackboardLearn while other faculty will want to build new courses in Blackboard Learn. If you do not want to import aparticular section, the content package for a section can be removed from themigrate directory before theimport as described in Step 5: Import CE 8 Sections into Blackboard Learn as Courses. As a result, the coursewill be created in Blackboard Learn, but the CE 8 content will not be imported.

Assigning Data Source KeysWhen using Blackboard Learn - Enterprise Edition, all data that is moved to the Blackboard Learn database istagged with a data source identifier, called a data source key, so that the dataset can bemanaged using thesnapshot/bin tool. For example, youmay choose to identify all Fall 2008 records imported from CE 8withthe data source key “CE_FALL_2009” and all Spring 2010 records with the data source key “CE_SPRING_2010.”

Enterprise Edition clients should consider creating a data source key for each set of courses beingmoved.Blackboard recommends creating a data source key for each school term (or group of terms, if desired) andassigning that data source key to the appropriate courses during Step 5: Import CE 8 Sections into BlackboardLearn as Courses.

For steps to verify or create a data source key, see Data Source Keys. To learnmore about data source keysand the snapshot/bin tool, see About the Snapshot Tool.

Resolving Data ConflictsIf your Blackboard Learn system contains any pre-existing data, Blackboard strongly recommends using aconflict resolution switch when completing Step 3: Import CE 8 User Data into Blackboard Learn and Step 5:Import CE 8 Sections into Blackboard Learn as Courses. Without one of these switches, data collisions maycause the import to fail. To learnmore, see LMSImport Switches for CE 8.


9.1 S

P6 BETA D

RAFT


Including EnrollmentsWhen youmove your data, you can choose whether to include all enrollments or to include only instructorenrollments as described in Step 6: Import CE 8 Enrollments into Blackboard Learn . Your decision depends onwhether you have built an SIS integration against Blackboard Learn.



Step 1: Install Blackboard LearnInstall Blackboard Learn 9.1 on hardware separate from your CE 8 installation.


Step 2: Export All Data from CE 8All data from the CE 8 institutionmust be exported so that the appropriate data can be imported into BlackboardLearn. This process is completed using the System Integration API’s siapi command. The resultingsnapshot.xml file will be used in each of the import steps in the upgrade process.

Complete this procedure on the first managed node using the command line on the CE 8 server.

1. Log in to the CE 8 server with system administrator privileges.2. Create a directory for your migration data using the following command.

UNIX:


Windows:


3. Navigate to the CE 8 directory using the following command.

UNIX:

cd /BEA directory/weblogic92/config/CE8 directory

Windows:

cd \BEA directory\weblogic92\config\CE8 directory

4. Run the command to retrieve the glcId that identifies the institution for which you want to exportdata.

UNIX:

./siapi.sh p

Windows:

siapi.cmd p

5. Export the CE 8 data to a snapshot.xml file using the following command.

UNIX:

./siapi.sh ims export snapshot /tmp/migrateToLearn/snapshot.xml --glcId=glcId --username=username --password=password


9.1 S

P6 BETA D

RAFT





Windows:

siapi.cmd ims export snapshot c:\temp\migrateToLearn\snapshot.xml --glcId==glcId --username=username --password=password

6. Open the resulting snapshot.xml file using a text editor, scroll to the very bottom of the file, andensure the last line is </enterprise>. If the file does not end with this line, the JVM on themachinemight have run out of memory during the export. Contact Blackboard Client Support.

Note: If the file is larger than 5MB, youmay need to use a text editor that can handle large files,such as TextPad.

Step 3: Import CE 8 User Data into Blackboard LearnAll users from the CE 8 institutionmust added to the Blackboard Learn user database. This process iscompleted using the LMSImport command and the snapshot.xml file resulting from Step 2: Export All Datafrom CE 8.

Importing user data into Blackboard Learn from an existing system preserves user account data such as loginID, role, and so on, but user-related data such as passwords, quiz attempts, sectionmembership information,group enrollment, and so on will not be included. For specific information about lost and retained data, refer toUnderstanding the Change from CE 8 to Blackboard Learn 9.1.





UNIX:

mkdir /tmp/migrateFromCE

Windows:

mkdir c:\temp\migrateFromCE

3. Copy the snapshot.xml file from the migrateToLearn directory on the CE 8 server to themigrateFromCE directory on the Blackboard Learn server.


UNIX:

cd /Learn directory/blackboard/tools/admin

Windows:

cd \Learn directory\blackboard\tools\admin

5. Import the user data from the snapshot.xml file using the LMSImport command and theappropriate switches. To learnmore about the available switches, see LMSImport Switches for CE8.




9.1 S

P6 BETA D

RAFT



UNIX:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml --ds=data source key --no_courses --no_enrollments [--conflict_prefix prefix] [--conflict_suffixsuffix] [--always]

For example:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml --ds=CE_FALL_2009 --no_courses --no_enrollments --conflict_prefix CE_ --always

Windows:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml --ds=data source key --no_courses --no_enrollments [--conflict_prefix prefix] [--conflict_suffixsuffix] [--always]

For example:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml --ds=CE_FALL_2009 --no_courses --no_enrollments --conflict_prefix CE_ --always

A running count of the records processed displays. The bb-services-log-integration-jdbc.txt log file is created and stored in the Learn_home/blackboard/logs/snapshotdirectory on the Blackboard Learn server for users that fail to import.

Step 4: Export Section Content Packages from CE 8The content from the desired sections in the CE 8 institutionmust be exported as packages so that they can beimported into Blackboard Learn. This process is completed using the existing backup_request.xmlconfiguration file and the backupRestoreCLI command. The resulting packages will be used in Step 5:Import CE 8 Sections into Blackboard Learn as Courses.

WARNING! Exporting the content packages can be a very time-consuming process. Blackboardrecommends exporting subsets of your sections or using a node outside the load-balancing pool.In addition, exporting large amounts of data can result is Out of Memory errors. If enoughmemory isavailable, these errors may be caused by the current heap size. To avoid these errors, increase theCOMMAND_LINE_JVM_OPTIONS max heap size in the startup.properties file on the CE 8 serverbefore running the export.

Complete this procedure on any managed node using the command line on the CE 8 server.

1. Log in to the CE 8 server with system administrator privileges for the institution.2. Navigate to the CE 8 directory using the following command.

UNIX:

cd /BEA directory/weblogic92/config/CE8 directory

Windows:

cd \BEA directory\weblogic92\config\CE8 directory

3. Copy the backup_request.xml file from the CE8 directory on the CE 8 server to themigrateToLearn folder on the Blackboard Learn server.

4. Using a text editor, open and edit the backup_request.xml file to export the desired contentpackages:


9.1 S

P6 BETA D

RAFT


To export the content of all sections in CE 8, edit the query_item column_name parameter asfollows:

<query_item column_name="Source Id" condition="notBlank" value=""operator="and"/>

To export only certain sections from CE 8, edit the query_item column_name using theinformation in the Vista 8/CE 8 Enterprise Operations Guide available on Behind the Blackboard.

5. Create the content packages specified in the backup_request.xml file using thebackupRestoreCLI command.

UNIX:

./backupRestoreCLI.sh --action=backup --backupdir=/tmp/migrateToLearn --configfile=/tmp/migrateToLearn/backup_request.xml --logfile=/tmp/migrateToLearn/archive.log --username=username --password=password--glcid=glcId

Windows:

backupRestoreCLI.cmd --action=backup --backupdir=c:\temp\migrateToLearn --configfile=c:\temp\migrateToLearn\backup_request.xml --logfile=c:\temp\migrateToLearn\archive.log --username=username --password=password --glcid=glcId

6. Copy the resulting content packages (*.bak) from the migrateToLearn directory on the CE 8server to the migrateFromCE directory on the Blackboard Learn server.

Step 5: Import CE 8 Sections into Blackboard Learn as CoursesThe import sections process is completed using the LMSImport command, the snapshot.xml file resultingfrom Step 2: Export All Data from CE 8, and the content packages resulting from Step 4: Export SectionContent Packages from CE 8.

If you do not want to import the content for a particular section, delete the content package for that section fromthe migrateFromCE directory before completing this procedure. The course will be created in BlackboardLearn, but the CE 8 content will not be imported.

Note: Enterprise Edition clients only: Before you begin, make sure that you have created a data source key forthe sections being imported. To learnmore, see Assigning Data Source Keys.



UNIX:


Windows:


3. Import the section content from the snapshot.xml file and the content packages (*.bak) usingthe LMSImport command and the appropriate switches. To learnmore about the availableswitches, see LMSImport Switches for CE 8.



UNIX:


9.1 S

P6 BETA D

RAFT

https://behind.blackboard.com/s/cevista/refcenter/docs/details.Bb?DocumentID=3248&pid=200&rid=5765&dt=







./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml --ds=data source key --pkg_dir=/tmp/migrateFromCE --no_users --no_enrollments [--conflict_prefixprefix] [--conflict_suffix suffix] --always --i course material type

For example:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml --ds=CE_FALL_2009 --pkg_dir=/tmp/migrateFromCE --no_users --no_enrollments --conflict_prefix CE_ --always --i Alignments,Announcement,Assessment,Calendar

Windows:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml --ds=data source key --pkg_dir=c:\temp\migrateFromCE --no_users --no_enrollments [--conflict_prefixprefix] [--conflict_suffix suffix] --always --i course material type

For example:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml --ds=CE_FALL_2009 --pkg_dir=c:\temp\migrateFromCE --no_users --no_enrollments --conflict_prefix CE_--always --i Alignments,Announcement,Assessment,Calendar



UNIX:


Windows:


Batch Import Sections as Courses Using an Alternative to the SnapshotToolBlackboard Learn includes a tool for handling the import of a number of Sections as Courses at once as well asthe import of files that exceed the default maximum upload limit. This tool will process a batch file that includesthe Section/Course ID and the name. Accepted import file type extension is .EPK as generated by CE 8.

How to Create an Import Batch FileA batch file used with the batch_ImportExport tool only has two values in each row, the Section/Course ID andthe full path to the backup package. When running an Import action, the specified path and file name point to thegenerated backup package associated with the destination Course ID.


Import ExamplesHIST101, C:\Course_archives\Archive_File_HIST101.epk





9.1 S

P6 BETA D

RAFT



Windows Syntax:



UNIX Syntax:



ArgumentDescription

path_to_file



virtual_hostname




Windows:

OPTS="%OPTS -Xmx6g"

UNIX:

OPTS="$OPTS -Xmx6g"

Step 6: Import CE 8 Enrollments into Blackboard LearnIf you have an SIS integration, you do not need to import the enrollments into Blackboard Learn. The SISintegration will handle the enrollments for upcoming school terms. You can skip this step.


The import enrollments process is completed using the LMSImport command and the snapshot.xml fileresulting from Step 2: Export All Data from CE 8.


9.1 S

P6 BETA D

RAFT




UNIX:


Windows:


3. Import the enrollments from the snapshot.xml file using the LMSImport command and theappropriate switches. To learnmore about the available switches, see LMSImport Switches for CE8.




UNIX:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml --ds=data source key --no_users --no_courses [--instr_only]

For example:

./LMSImport.sh --file=/tmp/migrateFromCE/snapshot.xml --ds=CE_FALL_2009 --no_users --no_courses

Windows:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml --ds=data source key --no_users --no_courses [--instr_only]

For example:

LMSImport.cmd --file=c:\temp\migrateFromCE\snapshot.xml --ds=CE_FALL_2009 --no_users --no_courses


Data Source KeysWhen using Blackboard Learn - Enterprise Edition, all data that is moved to the Blackboard Learn database canbe tagged with a data source identifier, called a data source key, so that the dataset can bemanaged using thesnapshot/bin tool. For example, youmay choose to identify all Fall 2009 records imported from CE 8 usingthe data source key “CE_FALL_2009” and all Spring 2010 records using the data source key “CE_SPRING_2010.”

This section provides the steps to check for existing data source keys and to create a new data source key.




9.1 S

P6 BETA D

RAFT


UNIX:


Windows:



UNIX:

./dsm.sh –f LIST

Windows:

dsm.cmd –f LIST



UNIX:


Windows:




UNIX:


For example:

./dsm.sh –f CREATE –b CE_FALL_2009 –d "All Fall 2009 Sections from CE migrationto Learn"

Windows:


For example:

dsm.cmd –f CREATE –b CE_FALL_2009 –d "All Fall 2009 Sections from CE migrationto Learn"

LMSImport Switches for CE 8The following table describes the available switches for the LMSImport command.


9.1 S

P6 BETA D

RAFT


Switch Description



The full path to and the name of the file (snapshot.xml) that contains the data exported fromCE 8 in Step 2: Export All Data from CE 8.

--pkg_dir fullpath topackages

Required in Step 5: Import CE 8 Sections into Blackboard Learn as Courses.

The full path to the directory where the course content packages (*.bak) were saved in Step 4:Export Section Content Packages from CE 8.

--ds datasource key


Required in Step 3: Import CE 8 User Data into Blackboard Learn, Step 5: Import CE 8Sections into Blackboard Learn as Courses, and Step 6: Import CE 8 Enrollments intoBlackboard Learn .


--no_courses Required in Step 3: Import CE 8 User Data into Blackboard Learn and Step 6: Import CE 8Enrollments into Blackboard Learn .

Do not import the available section shells.

--no_enrollments

Required in Step 3: Import CE 8 User Data into Blackboard Learn and Step 5: Import CE 8Sections into Blackboard Learn as Courses.


--no_users Required in Step 5: Import CE 8 Sections into Blackboard Learn as Courses and Step 6: ImportCE 8 Enrollments into Blackboard Learn ..


--no_content Optional. Import the section shells, but do not import the available content. This switch issuperseded by the --no_courses switch. The --pkg_dir switch is not effective when usedwith this switch.

--no_xlist Optional in Step 5: Import CE 8 Sections into Blackboard Learn as Courses.



--instr_only Optional in Step 6: Import CE 8 Enrollments into Blackboard Learn .








9.1 S

P6 BETA D

RAFT

Upgrades > Vista 8 to Learn 9.1

Switch Description













Vista 8 to Learn 9.1

Before You Begin




l Consider whether to implement Blackboard Learn in a virtualized environment. To learnmore, seeVirtualizing the Blackboard Reference Architecture .




l Install themost recent Vista 8 Service Pack.

Note: Blackboard recommends that MS SQL clients use Vista 8.0.4.

l Back up all data and store copies of the backup files on a local machine or drive.l Confirm that Blackboard supports your server and database configuration. This information is

available in "Supported Technologies" in the Release Notes for the release that you are installing.


9.1 S

P6 BETA D

RAFT





l To reduce the amount of time it takes to complete the upgrade, clean up old sections on the Vista 8server.

l Enterprise Edition clients only: Create a unique Data Source Key to identify the data imported fromVista 8. To learnmore, see Data Source Keys.

Understanding the ProcessSignificant planning and preparation is necessary to upgrade all sections to Blackboard Learn coursessuccessfully. The steps involved depend on licensing, hardware, existing Blackboard systems, andinstitutional policies and procedures.

Users and sections aremoved from Vista 8 to Blackboard Learn using various export and import operations.Upgrading from Vista 8 to Blackboard Learn involves the following steps:


Step 2: Export All Data from Vista 8 from Vista 8. This data will be used throughout the upgrade process.

Step 3: Import Vista 8 User Data into Blackboard Learn.

Step 4: Export Section Content Packages from Vista 8.

Step 5: Import Vista 8 Sections into Blackboard Learn as Courses.

Step 6: Import Vista 8 Enrollments into Blackboard Learn .

During the upgrade process, you have a variety of choices that depend on your institution’s needs. It isimportant to decide when and what data you plan tomove.

After all sections have beenmoved and are active in Blackboard Learn, you can archive and then turn off thelegacy Vista 8 system. All users in the institution will log into Blackboard Learn using a new password, and thelegacy system will no longer need to be used or maintained.

Deciding When to UpgradeIt is important to decide how Blackboard Learn will be introduced to faculty and students. Blackboardrecommends moving courses between terms tominimize disruptions.

If your institution hosts active sections 365 days per year, you will need to run both the Blackboard Learnsystem and the legacy Vista 8 system in productionmode while you complete your upgrade. Blackboardrecommends that youmove all of your data to the Blackboard Learn system and then set the courses that arestill being hosted in the production Vista 8 system as Inactive in Blackboard Learn until the sections on Vista 8have ended. When the section ends, you can activate the course in Blackboard Learn.

Deciding Which Sections to MoveAll of the Vista 8 sections can be exported andmoved to Blackboard Learn as courses, but youmay not want toexport older versions of the same section or other groups of sections. Thebackup_request.xml file,described in Step 4: Export Section Content Packages from Vista 8, can be edited to specify which sections toexport.

Depending on your institution’s needs, some faculty will want to upgrade their Vista 8 section to BlackboardLearn while other faculty will want to build new courses in Blackboard Learn. If you do not want to import aparticular section, the content package for a section can be removed from themigrate directory before theimport as described in Step 5: Import Vista 8 Sections into Blackboard Learn as Courses. As a result, thecourse will be created in Blackboard Learn, but the Vista 8 content will not be imported.


9.1 S

P6 BETA D

RAFT


Assigning Data Source KeysWhen using Blackboard Learn - Enterprise Edition, all data that is moved to the Blackboard Learn database istagged with a data source identifier, called a data source key, so that the dataset can bemanaged using thesnapshot/bin tool. For example, youmay choose to identify all Fall 2008 records imported from Vista 8 withthe data source key “VISTA_FALL_2009” and all Spring 2010 records with the data source key “VISTA_SPRING_2010.”

Enterprise Edition clients should consider creating a data source key for each set of courses beingmoved.Blackboard recommends creating a data source key for each school term (or group of terms, if desired) andassigning that data source key to the appropriate courses during Step 5: Import Vista 8 Sections intoBlackboard Learn as Courses. For steps to verify or create a data source key, see Data Source Keys. To learnmore about data source keys and the snapshot/bin tool, see About the Snapshot Tool.

Resolving Data ConflictsIf your Blackboard Learn system contains any pre-existing data, Blackboard strongly recommends using aconflict resolution switch when completing Step 3: Import Vista 8 User Data into Blackboard Learn and Step 5:Import Vista 8 Sections into Blackboard Learn as Courses. Without one of these switches, data collisions maycause the import to fail. To learnmore, see LMSImport Switches for Vista 8.

Including EnrollmentsWhen youmove your data, you can choose whether to include all enrollments or to include only instructorenrollments as described in Step 6: Import Vista 8 Enrollments into Blackboard Learn .. Your decision dependson whether you have built an SIS integration against Blackboard Learn.



Step 1: Install Blackboard LearnInstall Blackboard Learn 9.1 on hardware separate from your Vista 8 installation.


Step 2: Export All Data from Vista 8All data from the Vista 8 institutionmust be exported so that the appropriate data can be imported intoBlackboard Learn. This process is completed using the System Integration API’s siapi command. Theresulting snapshot.xml file will be used in each of the import steps in the upgrade process.

Complete this procedure on the first managed node using the command line on the Vista 8 server.

1. Log in to the Vista 8 server with system administrator privileges.2. Create a directory for your migration data using the following command.

UNIX:


Windows:



9.1 S

P6 BETA D

RAFT





3. Navigate to the Vista 8 directory using the following command.

UNIX:

cd /BEA directory/weblogic92/config/Vista8 directory

Windows:

cd \BEA directory\weblogic92\config\Vista8 directory

4. Run the command to retrieve the glcId that identifies the institution for which you want to exportdata.

UNIX:

./siapi.sh p

Windows:

siapi.cmd p

5. Export the Vista 8 data to a snapshot.xml file using the following command.

UNIX:

./siapi.sh ims export snapshot /tmp/migrateToLearn/snapshot.xml --glcId=glcId --username=username --password=password

Windows:

siapi.cmd ims export snapshot c:\temp\migrateToLearn\snapshot.xml --glcId==glcId --username=username --password=password

6. Open the resulting snapshot.xml file using a text editor, scroll to the very bottom of the file, andensure the last line is </enterprise>. If the file does not end with this line, the JVM on themachinemight have run out of memory during the export. Contact Blackboard Client Support.

Note: If the file is larger than 5MB, youmay need to use a text editor that can handle large files,such as TextPad.

Step 3: Import Vista 8 User Data into Blackboard LearnAll users from the Vista 8 institutionmust added to the Blackboard Learn user database. This process iscompleted using the LMSImport command and the snapshot.xml file resulting from Step 2: Export All Datafrom Vista 8.

Importing user data into Blackboard Learn from an existing system preserves user account data such as loginID, role, and so on, but user-related data such as passwords, quiz attempts, sectionmembership information,group enrollment, and so on will not be included. For specific information about lost and retained data, refer toUnderstanding the Change from Vista 8 to Blackboard Learn 9.1.





UNIX:


9.1 S

P6 BETA D

RAFT


mkdir /tmp/migrateFromVista

Windows:

mkdir c:\temp\migrateFromVista

3. Copy the snapshot.xml file from the migrateToLearn directory on the Vista 8 server to themigrateFromVista directory on the Blackboard Learn server.


UNIX:


Windows:


5. Import the user data from the snapshot.xml file using the LMSImport command and theappropriate switches. To learnmore about the available switches, see LMSImport Switches forVista 8.




UNIX:

./LMSImport.sh --file=/tmp/migrateFromVista/snapshot.xml --ds=data source key --no_courses --no_enrollments [--conflict_prefix prefix] [--conflict_suffixsuffix] [--always]

For example:

./LMSImport.sh --file=/tmp/migrateFromVista/snapshot.xml --ds=VISTA_FALL_2009 --no_courses --no_enrollments --conflict_prefix Vista_ --always

Windows:

LMSImport.cmd --file=c:\temp\migrateFromVista\snapshot.xml --ds=data source key--no_courses --no_enrollments [--conflict_prefix prefix] [--conflict_suffixsuffix] [--always]

For example:

LMSImport.cmd --file=c:\temp\migrateFromVista\snapshot.xml --ds=VISTA_FALL_2009--no_courses --no_enrollments --conflict_prefix Vista_ --always

A running count of the records processed displays. The bb-services-log-integration-jdbc.txt log file is created and stored in the Learndirectory/blackboard/logs/snapshot directory on the Blackboard Learn server for usersthat fail to import.

Step 4: Export Section Content Packages from Vista 8The content from the desired sections in the Vista 8 institutionmust be exported as packages so that they canbe imported into Blackboard Learn. This process is completed using the existing backup_request.xmlconfiguration file and the backupRestoreCLI command. The resulting packages will be used in Step 5:Import Vista 8 Sections into Blackboard Learn as Courses.


9.1 S

P6 BETA D

RAFT


WARNING! Exporting the content packages can be a very time-consuming process. Blackboardrecommends exporting subsets of your sections or using a node outside the load-balancing pool.In addition, exporting large amounts of data can result is Out of Memory errors. If enoughmemory isavailable, these errors may be caused by the current heap size. To avoid these errors, increase theCOMMAND_LINE_JVM_OPTIONS max heap size in the startup.properties file on the Vista 8server before running the export.

Complete this procedure on any managed node using the command line on the Vista 8 server.

1. Log in to the Vista 8 server with system administrator privileges for the institution.2. Navigate to the Vista 8 directory using the following command.

UNIX:

cd /BEA directory/weblogic92/config/Vista8 directory

Windows:

cd \BEA directory\weblogic92\config\Vista8 directory

3. Copy the backup_request.xml file from the Vista8 directory on the Vista 8 server to themigrateToLearn folder on the Blackboard Learn server.

4. Using a text editor, open and edit the backup_request.xml file to export the desired contentpackages:

To export the content of all sections in Vista 8, edit the query_item column_name parameter asfollows:

<query_item column_name="Source Id" condition="notBlank" value=""operator="and"/>

To export only certain sections from Vista 8, edit the query_item column_name using theinformation in the Vista 8/CE 8 Enterprise Operations Guide available on Behind the Blackboard.

5. Create the content packages specified in the backup_request.xml file using thebackupRestoreCLI command.

UNIX:

./backupRestoreCLI.sh --action=backup --backupdir=/tmp/migrateToLearn --configfile=/tmp/migrateToLearn/backup_request.xml --logfile=/tmp/migrateToLearn/archive.log --username=username --password=password--glcid=glcId

Windows:

backupRestoreCLI.cmd --action=backup --backupdir=c:\temp\migrateToLearn --configfile=c:\temp\migrateToLearn\backup_request.xml --logfile=c:\temp\migrateToLearn\archive.log --username=username --password=password --glcid=glcId

6. Copy the resulting content packages (*.bak) from the migrateToLearn directory on the Vista 8server to the migrateFromVista directory on the Blackboard Learn server.

Step 5: Import Vista 8 Sections into Blackboard Learn as CoursesThe import sections process is completed using the LMSImport command, the snapshot.xml file resultingfrom Step 2: Export All Data from Vista 8,and the content packages resulting from Step 4: Export SectionContent Packages from Vista 8.


9.1 S

P6 BETA D

RAFT








If you do not want to import the content for a particular section, delete the content package for that section fromthe migrateFromVista directory before completing this procedure. The course will be created in BlackboardLearn, but the Vista 8 content will not be imported.

Note: Enterprise Edition clients only: Before you begin, make sure that you have created a data source key forthe sections being imported. To learnmore, see Assigning Data Source Keys.



UNIX:


Windows:


3. Import the section content from the snapshot.xml file and the content packages (*.bak) usingthe LMSImport command and the appropriate switches. To learnmore about the availableswitches, see LMSImport Switches for Vista 8.



UNIX:

./LMSImport.sh --file=/tmp/migrateFromVista/snapshot.xml --ds=data source key --pkg_dir=/tmp/migrateFromVista --no_users --no_enrollments [--conflict_prefixprefix] [--conflict_suffix suffix] --always --i course material type

For example:

./LMSImport.sh --file=/tmp/migrateFromVista/snapshot.xml --ds=VISTA_FALL_2009 --pkg_dir=/tmp/migrateFromVista --no_users --no_enrollments --conflict_prefixVista_ --always --i Alignments,Announcement,Assessment,Calendar

Windows:

LMSImport.cmd --file=c:\temp\migrateFromVista\snapshot.xml --ds=data source key--pkg_dir=c:\temp\migrateFromVista --no_users --no_enrollments [--conflict_prefix prefix] [--conflict_suffix suffix] --always --i course material type

For example:

LMSImport.cmd --file=c:\temp\migrateFromVista\snapshot.xml --ds=VISTA_FALL_2009--pkg_dir=c:\temp\migrateFromVista --no_users --no_enrollments --conflict_prefix Vista_ --always --i Alignments,Announcement,Assessment,Calendar



UNIX:


Windows:



9.1 S

P6 BETA D

RAFT


Batch Import Sections as Courses Using an Alternative to the SnapshotToolBlackboard Learn includes a tool for handling the import of a number of Sections as Courses at once as well asthe import of files that exceed the default maximum upload limit. This tool will process a batch file that includesthe Section/Course ID and the name. Accepted import file type extension is .BAK as generated by Vista.

How to Create an Import Batch FileA batch file used with the batch_ImportExport tool only has two values in each row, the Section/Course ID andthe full path to the backup package. When running an Import action, the specified path and file name point to thegenerated backup package associated with the destination Course ID.


Import ExamplesHIST101, C:\Course_archives\Archive_File_HIST101.bak

HIST301, C:\Course_archives\Archive_File_HIST301.bak

HIST401, C:\Course_archives\Archive_File_HIST401.bak



Windows Syntax:



UNIX Syntax:



ArgumentDescription

path_to_file



virtual_hostname



9.1 S

P6 BETA D

RAFT




Windows:

OPTS="%OPTS -Xmx6g"

UNIX:

OPTS="$OPTS -Xmx6g"

Note: Files with the .BAK extensionmust be less than 4GB to successfully import.

Step 6: Import Vista 8 Enrollments into Blackboard LearnIf you have an SIS integration, you do not need to import the enrollments into Blackboard Learn. The SISintegration will handle the enrollments for upcoming school terms. You can skip this step.


The import enrollments process is completed using the LMSImport command and the snapshot.xml fileresulting from Step 2: Export All Data from Vista 8.



UNIX:


Windows:


3. Import the enrollments from the snapshot.xml file using the LMSImport command and theappropriate switches. To learnmore about the available switches, see LMSImport Switches forVista 8.




UNIX:

./LMSImport.sh --file=/tmp/migrateFromVista/snapshot.xml --ds=data source key --no_users --no_courses [--instr_only]

For example:

./LMSImport.sh --file=/tmp/migrateFromVista/snapshot.xml --ds=VISTA_FALL_2009 --no_users --no_courses

Windows:


9.1 S

P6 BETA D

RAFT


LMSImport.cmd --file=c:\temp\migrateFromVista\snapshot.xml --ds=data source key--no_users --no_courses [--instr_only]

For example:

LMSImport.cmd --file=c:\temp\migrateFromVista\snapshot.xml --ds=VISTA_FALL_2009--no_users --no_courses


Data Source KeysWhen using Blackboard Learn - Enterprise Edition, all data that is moved to the Blackboard Learn database canbe tagged with a data source identifier, called a data source key, so that the dataset can bemanaged using thesnapshot/bin tool. For example, youmay choose to identify all Fall 2009 records imported from Vista 8using the data source key “VISTA_FALL_2009” and all Spring 2010 records using the data source key “VISTA_SPRING_2010.”

This section provides the steps to check for existing data source keys and to create a new data source key.



UNIX:


Windows:



UNIX:

./dsm.sh –f LIST

Windows:

dsm.cmd –f LIST



UNIX:


Windows:



9.1 S

P6 BETA D

RAFT




UNIX:


For example:

./dsm.sh –f CREATE –b VISTA_FALL_2009 –d "All Fall 2009 Sections from Vistamigration to Learn"

Windows:


For example:

dsm.cmd –f CREATE –b VISTA_FALL_2009 –d "All Fall 2009 Sections from Vistamigration to Learn"

LMSImport Switches for Vista 8The following table describes the available switches for the LMSImport command.

Switch Description



The full path to and the name of the file (snapshot.xml) that contains the data exported fromVista 8 in Step 2: Export All Data from CE 8.

--pkg_dir fullpath topackages

Required in Step 5: Import CE 8 Sections into Blackboard Learn as Courses.

The full path to the directory where the course content packages (*.bak) were saved in Step 4:Export Section Content Packages from CE 8.

--ds datasource key


Required in Step 3: Import CE 8 User Data into Blackboard Learn, Step 5: Import CE 8Sections into Blackboard Learn as Courses, and Step 6: Import CE 8 Enrollments intoBlackboard Learn .


--no_courses Required in Step 3: Import CE 8 User Data into Blackboard Learnand Step 6: Import CE 8Enrollments into Blackboard Learn .

Do not import the available section shells.

--no_enrollments

Required in Step 3: Import CE 8 User Data into Blackboard Learn and Step 5: Import CE 8Sections into Blackboard Learn as Courses.


--no_users Required in Step 5: Import CE 8 Sections into Blackboard Learn as Courses and Step 6: ImportCE 8 Enrollments into Blackboard Learn .


--no_content Optional. Import the section shells, but do not import the available content. This switch issuperseded by the --no_courses switch. The --pkg_dir switch is not effective when usedwith this switch.


9.1 S

P6 BETA D

RAFT

Upgrades > Upgrading the Blackboard Learn License Only

Switch Description

--no_xlist Optional in Step 5: Import CE 8 Sections into Blackboard Learn as Courses.



--instr_only Optional in Step 6: Import CE 8 Enrollments into Blackboard Learn .



















Upgrading the Blackboard Learn License OnlyUsing theProvide New License Installer option, administrators can process a new license file to enable ordisable Blackboard Learn capabilities. For example, if you are running Blackboard Learn with only coursedelivery and then your school licenses content management, the process for turning on the Content Collectionis to upgrade the license.

If the license file is renamed is renamed bb-license.xml and placed in the same directory as the Installer,the Installer will automatically detect the license file.

WARNING! When providing a new license, downtime is required. This installation option will perform a fullupgrade, shutting down services.


9.1 S

P6 BETA D

RAFT

Upgrades > Upgrading the Blackboard Learn License Only

How to Upgrade the Blackboard Learn License1. Obtain a new license file from Blackboard. To request a current license file, contact your

Blackboard Client Representative.2. Rename the license file bb-license.xml and place it in the same directory as the Installer. Be

sure not to confuse the new license file with the old license file.3. Launch the Updater. Windows users may click on the Updater to launch it. UNIX users should run

the following command to launch the Updater:/usr/local/bbinstaller/java –jar updater_file -gui

A welcomemessage appears with a reminder to read the Release Notes for the release that you areinstalling and installation instructions before updating. Click Next to continue.

4. The first page asks for the directory where Blackboard will be found. Click Next to accept thedefault or enter a new value and then click Next. If Blackboard Learn is not found in the directoryprovided, the Updater will attempt to install at the given location.

5. The next prompt presents several options. The options areUpdate, Provide new License file,Uninstall Blackboard Learn, andUninstall appserver. Select Provide new License file andclick Next.

6. The location of the license file will populate automatically. If it does not, enter the path to thelicense file. Click Next to continue.

7. A message will appear that the license upgrade is ready to proceed. Click Next to start theUpdater. Do not close the command line window or any of the other windows that pop-up during theupdate.


9.1 S

P6 BETA D

RAFT



Databases > About the Databases

Databases

About the DatabasesBlackboard Learn initially installs three databases and three database users. This topic reviews the databasesand database users of Blackboard Learn.

Administrators should not add data directly to the database or modify data in the database directly. Doing somay create serious problems in the system.

BBLEARN_ADMINThis databasemanages information about the databases. Legacy users will instead use the database nameBBADMIN.

BBLEARNThis is themain database. Legacy users will instead use the database name BB_BB60.

BBLEARN_STATSThis is the statistics database. Legacy users will instead use the database name BB_BB60_STATS. It is usefulfor Administrators who wish to generate reports on usage, performance, and other metrics. Tracking data issent to this database daily.

Database UsersThe following database users are created when Blackboard Learn is installed.

l bblearn_adminl bblearnl bblearn_statsl services.threaddumpl services.statusS

The bblearn_report user has limited access to view the BBLEARN database and can only see a subset oftables and columns.

Change the value in the bb-config.properties file and then run the PushConfigUpdates command tochange the password of a database user. Remember that the passwordmust also be changed within thedatabase tomatch the new password or the Blackboard Learn will not work properly.

Note: For performance reasons, CURSOR_SHARING should be set to EXACT or FORCE, especially when usingOracle and licensing content management. Access issues with groups and files may also occur.


9.1 S

P6 BETA D

RAFT

Databases > Database Schema Legacy Information and Document Stores

Database Schema Legacy Information and Document Stores

Database Schema NamingWhen upgrading an existing instance or creating a testing environment for an institution using the legacydatabase schema names, note that database schema names have received a re-work for this latest version ofBlackboard Learn. Manual database schema name changes on an existing schema should only be done withthe assistance of Blackboard Client Support.

When creating testing environments for a legacy environment, specify the legacy information in the databaseidentifier option in the Blackboard Learn Installer as shown in the following table. The five CMS_FILES_*schemas have beenmerged into a single CMS_DOC schema.

SchemaName Legacy Schema Name

BBLEARN BB_BB60

BBLEARN_ADMIN

BBADMIN

BBLEARN_STATS

BB_BB60_STATS

CMS CMS

CMS_DOC CMS_FILES_* (CMS_FILES_COURSES, CMS_FILES_INST, CMS_FILES_LIBRARY, CMS_FILES_ORG, CMS_FILES_USERS)

Starting Services in a SQL Environment

How to Start ServicesThe last step in the process of restoring the Blackboard Learn is to re-start all Blackboard services using thefollowing command. After starting the services, login to the system and sanity test the system.

How to Stop the Services1. Launch a command prompt from theWindows Start menu.2. Navigate to blackboard_home\tools\admin3. Start the iisadmin, bb-collab, and bb-tomcat services by typing the following command

and pressing the ENTER key:servicecontroller.bat services.start

Starting Services in an Oracle Environment

How to Start ServicesThe last step in the process of restoring the Blackboard Learn is to re-start all Blackboard services using thefollowing command. After starting the services, login to the system and sanity test the system.


9.1 S

P6 BETA D

RAFT

Databases > Oracle RAC Support on UNIX

./blackboard_home/tools/admin/ServiceController.sh services.start

Oracle RAC Support on UNIXOracle Real Application Clusters (RAC) provides advantages such as high availability, and failover byclusteringmultiple database instances. Blackboard Learn is installed and upgraded, by default, using the thinJDBC driver though the environment can later be configured to useOracle RAC. After the installation iscomplete, the OCI driver will be utilized to allow for transparent application failover and other advancedOracleconfigurations. Once the Blackboard Learn environment has been configured to useOracle RAC, subsequentupgrades will require returning to the JDBC driver until after the upgrade has completed.

ConfigurationConfiguring Blackboard Learn to connect with Oracle RAC is a supported configuration as of version 9.1 ofBlackboard Learn. Earlier versions of the application are considered customized solutions and assistance withthat type of configuration is available through Blackboard Consulting.

Prerequisitesl Oracle RAC environment has been installed and set up properly according to Oracle's

documentation.l Blackboard Learn 9.1 is installed and configured using one of the RAC instances with default JDBC

connectivityl Blackboard Learn 9.1 has been properly tested and updated with any customizations or advanced

configurations.l Failover has been tested at the database level with the Oracle RAC environment according to

Oracle's documentation.

How to Configure the Oracle RAC Environment1. Go to the oracle_home/network/admin folder.2. Make a backup of the tnsnames.ora file.

a. cp tnsnames.ora tnsnames.ora.single_date

b. cp tnsnames.ora.bb tnsnames.ora.bbsingle_date

3. Add entries to the tnsnames.ora.bb file whichmatch the RAC environment configuration. Inthe following tnsnames.ora example, the RAC consists of two instances on nodesrac01.foo.com and rac02.foo.com with the service name bb-rac-db:bbrac =

(DESCRIPTION=

(LOAD_BALANCE=on)

(FAILOVER=on )

(ADDRESS=

(PROTOCOL=tcp)(HOST = rac01.foo.com)(PORT=1521) )

(ADDRESS=

(PROTOCOL=tcp)(HOST = rac02.foo.com)(PORT=1521) )

(CONNECT_DATA=

(SERVICE_NAME= bb-rac-db)


9.1 S

P6 BETA D

RAFT


(FAILOVER_MODE=(TYPE=select)(METHOD=basic) )

)

)

4. Test the connection:sqlplus database_schema@alias_name

5. Stop your server by issuing ./blackboard_home/tools/admin/ServiceController.shservices.stop

6. Go to blackboard_home/config7. Open the bb-config.properties file to switch the JDBC driver as OCI and tns for RAC. The

alias for bbconfig.database.type.oracle.tns parameter must match the parameter asdefined in the tnsnames.ora.bb file.bbconfig.oracle.client.drivertype=oci

bbconfig.database.type.oracle.tns=bbrac

8. Connect to the database with a user that has permissions to the BBLEARN_CMS schema thenquery the database and update the connection.sqlplus database_schema@alias_name

SQL> select DB_USERNAME,DB_PASSWORD,JDBC_CONNECTION_URL from $cms_schema.XY_FILE_SYSTEMS;

SQL> update cms_schema.xy_file_systems set jdbc_connection_url='jdbc:oracle:oci:@bbrac ';

2 rows updated.

SQL> commit;

Commit complete.

9. Go to blackboard_home/tools/admin10. Launch the Push Config Updates script by issuing ./PushConfigUpdates.sh. To learnmore,

see PushConfigUpdates.11. Verify the application has connected to the Oracle RAC environment and is working as expected.

Note: The ORACLE_HOME location is defined by the property bbconfig.database.local.oracle.homein bb-config.properties. The default ORACLE_HOME is blackboard_home/apps/oracle-client/

How to Configure Single Instance Mode1. Verify that Blackboard Learnis connected to Oracle RAC instances and functioning properly.2. Stop your server by issuing ./blackboard_home/tools/admin/ServiceController.sh

services.stop

3. Go to blackboard_home/config4. Open the bb-config.properties file to switch back to the JDBC driver and unset tns for

RAC.bbconfig.oracle.client.drivertype=thin

bbconfig.database.type.oracle.tns=

5. Verify that the bbconfig.database.server.* parameters in bb-config.propertiespoints to one of the RAC instances as follows:bbconfig.database.server.name= rac01

bbconfig.database.server.fullhostname= rac01.foo.com

bbconfig.database.server.instancename= bb-rac-db01


9.1 S

P6 BETA D

RAFT


bbconfig.database.server.portnumber=1521

bbconfig.database.server.systemuserpassword=oracle

6. Connect to the database with a user that has permissions to the BBLEARN_CMS schema thenquery the database and update the connection where rac01 is the name of the first databaseinstance and bb-rac-db01 is the server namewhere the first instance is running :sqlplus database_schema@bbrac

SQL> select DB_USERNAME,DB_PASSWORD,JDBC_CONNECTION_URL from cms_schema.XY_FILE_SYSTEMS;

SQL> update cms_schema.xy_file_systems set jdbc_connection_url='jdbc:oracle:thin:@rac01:1521: bb-rac-db01';

2 rows updated.

SQL> commit;

Commit complete.

7. Go to blackboard_home/tools/admin8. Launch the Push Config Updates script by issuing ./PushConfigUpdates.sh. To learnmore,

see PushConfigUpdates.9. Verify the application has connected using the JDBC driver and all components are working as

expected.

How to Upgrade Blackboard Learn in an Oracle RAC Environment1. Prior to upgrading Blackboard Learn in anOracle RAC environment, all modifications to the

configurationmust be reversed. Follow the instructions in Configure Single InstanceMode toensure that properties relating to the database server are pointing to one RAC node.

2. Stop your server by issuing ./blackboard_home/tools/admin/ServiceController.shservices.stop

3. While connected to one of the RAC nodes, perform a standard upgrade of Blackboard Learn4. Verify the application has connected using the JDBC driver and all components are working as

expected.5. Follow the instructions in Configure the Oracle RAC Environment to reconfigure the application to

use anOracle RAC environment.

Special RAC Patches on Oracle RACProblem:

ORA-00600: internal error code, arguments: [kkocxj : pjpCtx] while complex sqls.

Solution:

To work around this Oracle bug, logon as sysdba and alter system set:

"_optimizer_push_pred_cost_based" = false scope =both;

Reference:

http://forums.oracle.com/forums/thread.jspa?threadID=836121


9.1 S

P6 BETA D

RAFT

http://forums.oracle.com/forums/thread.jspa?threadID=836121

Databases > Installing and Upgrading Small Scale Oracle

Best Practicesl Review all requirements for Blackboard Learn 9.1 application configuration prior to installationl Use only 1 application and database instance to configure the environment to connect to Oracle

RAC.l Always test application functionality to verify the application is working as expected.l Test failover of the database by shutting down one database instance and test the application

functionalityl Check netstat to ensure that the application is connected to the correct IP/alias for the instancel If you want to configure the application server, cloning the first application server and updating the

configuration files is themost efficient method for initial installationl If upgrading, always reverse configuration and customizations, test functionality before running the

installerl If you require additional planning or assistance with the configuration, contact Blackboard Consulting.

Installing and Upgrading Small Scale Oracle

About Small-Scale OracleBlackboard Learning System - Basic Edition and Blackboard Course Delivery - Basic Edition include a versionof Oracle® that is smaller than a full Oracle license and is designed to support the Basic Edition. This version ofOracle is called Small Scale Oracle® (SSO) and runs on a 32-bit UNIX-based operating system.

This section provides instructions for installing and upgrading Small Scale Oracle. These instructions areintended only for use with the version of Small Scale Oracle provided by Blackboard.

Installing Small Scale Oracle 10g

Before You BeginReview the following information before you begin installing Small Scale Oracle.

Space RequirementsBlackboard recommends that you have at least 20 GB of disk space available for your Small Scale Oracleinstallation.

Installation Location and PathsInstalling Small Scale Oracle 10g in the following location:

/usr/local/oracle/10g

Note: Do not install Small Scale Oracle in /usr/local/blackboard.

This document uses 10GPATH to represent the path to your Small Scale Oracle installation. For example, ifSmall Scale Oracle is installed in the recommended directory, 10GPATH would indicate the following location:

/usr/local/oracle/10g


9.1 S

P6 BETA D

RAFT


Password RequirementsWhen installing Small Scale Oracle, do not use the at sign (@) in any Oracle database user passwords. To besure that Oracle database user passwords do not violate Oracle rules for passwords, use only letters, numbers,and the underscore (_).

Note: It is permissible to use the at sign (@) in passwords for Blackboard Academic Suite user accounts.

Double-Check the Environment ConfigurationExecute the following command to check the user environment:

Solaris:

env|/usr/xpg4/bin/grep -E "ORACLE|NLS|PATH"|sort

Linux:

env|/bin/grep -E "ORACLE|NLS|PATH"|sort

Prepare the Database ServerTo prepare the destination database server for Small Scale Oracle, complete the Pre-Installation Steps for AllServers as well as the steps for your particular database server:

l Pre-Installation Steps for Red Hat Linux Servers

l Pre-Installation Steps for Solaris Servers

Pre-Installation Steps for All ServersBefore installing Small Scale Oracle on any database server, perform the steps in this section.

To prepare your database server:

1. Make sure that the server meets the requirements for your version of the Blackboard Basic Editionsoftware. For the list of requirements, see the Supported Server Configuration page for your versionin theMaintenance Center, which is accessible through Behind the Blackboard athttps://behind.blackboard.com.

2. Be sure that the correct version of GNUTar is installed on the database server.3. Place redo logs and data files onto separate physical devices to reduce I/O contention.4. All developer tools provided with the operating systemmust be installed. If the developer install

option was not selected during the installation of the operating system, install all developer toolsmanually. These files are located on your operating system's installationmedia. To learnmore, seeyour operating system documentation.

5. The database server must be on the same LAN as the application server and have a static IPaddress.

Pre-Installation Steps for Red Hat Linux ServersBefore installing Small Scale Oracle on Red Hat Linux, perform the steps in this section.

To prepare your Red Hat Linux server:

1. Log in to the database server as root.2. Make sure the following library packages (or later versions) are installed on your server:


9.1 S

P6 BETA D

RAFT



binutils-2.15.92.0.2-10.EL4 compat-db-4.1.25-9

compat-libstdc++-296-2.96-132.7.2 gcc-3.4.3-9.EL4

gcc-c++-3.4.3-9.EL4 glibc-2.3.4-2

glibc-common-2.3.4-2 gnome-libs-1.4.1.2.90-44.1

libaio-0.3.96 RPM libstdc++-3.4.3-9.EL4

libstdc++-devel-3.4.3-9.EL4 make-3.80-5

pdksh-5.2.14-30 sysstat-5.0.5-1

setarch-1.6-1

3. Add the following line to the /etc/security/limits.conf file:hard nofile 5000

start()

{

# Create keys if necessary

do_rsa1_keygen

do_rsa_keygen

do_dsa_keygen

# add the following line to work around a Linux bug in sshd

ulimit -SHn 5000

echo -n "Starting $prog:"

initlog -c "$SSHD $OPTIONS" && success || failure

RETVAL=$?

[ "$RETVAL" = 0 ] && touch /var/lock/subsys/sshd

echo

}

4. Close and save the file.5. Execute the following commands to create the Oracle user, the directories where the Oracle

binaries will reside, and set the Oracle user and dba group as the owner of these directories:mkdir /usr/local/oracle

mkdir 10GPATH

export ORACLE_BASE=/usr/local/oracle

groupadd dba

useradd –g dba –c “Oracle Owner” –d $ORACLE_BASE –m oracle

chown –R oracle:dba $ORACLE_BASE

6. Log in to the database server as the Oracle user using the following command:su - oracle

7. On the server where you are installing the database instance, add the following lines to the Oracleuser’s .bash_profile:ORACLE_BASE=/usr/local/oracle

ORACLE_SID=SSOSID

ORACLE_DATA=$ORACLE_BASE/oradata/$ORACLE_SID

ORACLE_HOME=$ORACLE_BASE/10g

LD_LIBRARY_PATH=$ORACLE_HOME/lib:$ORACLE_HOME/jdbc/lib

NLS_LANG=AMERICAN_AMERICA.UTF8


9.1 S

P6 BETA D

RAFT


export ORACLE_BASE ORACLE_DATA ORACLE_HOME ORACLE_SID

export LD_LIBRARY_PATH NLS_LANG

PATH=$ORACLE_HOME/bin:/usr/bin:/usr/sbin:/etc:$PATH

export PATH

The ORACLE_SID is case sensitive. Traditionally this value is defined using all uppercase letters.The SSOSIDmust meet the following requirements:

l Be unique on this server.l Cannot exceed 8 characters. Blackboard recommends 4-6 alphanumeric characters.l Not contain an underscore (_).

8. To update the environment, source the .bash_profile using the following command:. $HOME/.bash_profile

9. Exit from theOracle account, becoming root again.10. In the /etc/ folder, open the sysctl.conf file and add the following parameters:

kernel.sem = 250 32000 100 128

kernel.shmmax = 4294967295

net.ipv4.ip_local_port_range = 1024 65000

net.core.rmem_default = 262144

net.core.rmem_max = 262144

net.core.wmem_default = 262144

net.core.wmem_max = 262144

Note: The kernel.shmmax parameter specifies themaximum sharedmemory segment size.The value given here (4294967295, which is approximately 4 GB) assumes that the databaseserver has at least 4 GB of physical memory. If your server has more than 4GB, change this valueto greater than or equal to half of the server’s physical memory. Otherwise, the Oracle installer willissue a warning.

11. Reboot the database server machine.

Pre-Installation Steps for Solaris ServersBefore installing Small Scale Oracle on a Solaris server, perform the steps in this section.

To prepare your Solaris server:

1. Log in to the database server as root.2. Using the following commands, create a dba group and anOracle user, and then add theOracle

user to the dba group, which will own theOracle binaries.mkdir /usr/local/oracle

export ORACLE_BASE=/usr/local/oracle

groupadd dba

useradd –g dba –c “Oracle Software Owner” –d $ORACLE_BASE –m oracle

chown –R oracle:dba $ORACLE_BASE

3. Log in to the database server as the Oracle user you created.4. On the server where you are installing the database instance, add the following lines to the Oracle

user’s .profile:ORACLE_BASE=/usr/local/oracle

ORACLE_SID== SSOSID

ORACLE_DATA=$ORACLE_BASE/oradata/$ORACLE_SID


9.1 S

P6 BETA D

RAFT


ORACLE_HOME=$ORACLE_BASE/10g

LD_LIBRARY_PATH=$ORACLE_HOME/lib:$ORACLE_HOME/jdbc/lib

NLS_LANG=AMERICAN_AMERICA.UTF8

export ORACLE_BASE ORACLE_DATA ORACLE_HOME ORACLE_SID

export LD_LIBRARY_PATH NLS_LANG

PATH=$ORACLE_HOME/bin:/usr/bin:/usr/sbin:/etc:$PATH

export PATH

The ORACLE_SID is case sensitive. Traditionally this value is defined using all uppercase letters.The SSOSIDmust meet the following requirements:

l Be unique on this server.l Cannot exceed 8 characters. Blackboard recommends 4-6 alphanumeric characters.l Not contain an underscore (_).

5. To update the environment, source the .profile using the following command:. $HOME/.profile

6. Exit from theOracle account, becoming root again.7. In the /etc/ folder, add the following lines to the sysctl.conf file:

* oracle kernel configuration

forceload: sys/shmsys

set semsys:seminfo_semmni=100

set semsys:seminfo_semmns=3100

set semsys:seminfo_semmsl=1600

set shmsys:shminfo_shmmax=4294967295

set shmsys:shminfo_shmmin=1

set shmsys:shminfo_shmmni=100

set shmsys:shminfo_shmseg=10

set rlim_fd_max = 8192

set rlim_fd_cur = 1024

set semsys:seminfo_semopm=100

set semsys:seminfo_semvmx=32767

set noexec_user_stack=1

8. Reboot the database server machine.

Install the Small Scale Oracle 10g SoftwareFollow the steps in this section to install the Small Scale Oracle software provided with your Blackboard BasicEdition software.

Note: Make sure to use the default database data and index directories. Otherwise, the installation will fail.

To install the Small Scale Oracle software:

1. Download the Small Scale Oracle package from Behind the Blackboard. To locate the package,click Downloads, and then underView downloads by File Type, click Support Tools.

2. Log in to the database server as root.3. Move the Small Scale Oracle installation package to the /usr/local directory and unzip it using

the following commands:mv SSO-linux or solaris.tar.gz /usr/local


9.1 S

P6 BETA D

RAFT





cd /usr/local

gzip –d < SSO--linux or solaris.tar.gz | tar xvf -

4. Execute the following commands to run the installer:cd /usr/local/SSO

./BbInstallSSO.sh –b /usr/local/oracle -h 10GPATH -H OraDb10gHome -s SSOSID

5. Enter the following responses to the script:6. Press ENTER to keep /usr/local/bin as the default directory.7. Enter “Y” to overwrite the dbhome file.8. Enter “Y” to overwrite the oraenv file.9. Enter “Y” to overwrite the coraenv file.

Configure Small Scale Oracle 10gTo configure Small Scale Oracle, complete the following steps.

Grant Additional CONNECT Role PrivilegesPrior to Oracle 10g, Release 2, the CONNECT role was granted eight privileges: create session, createtable, create view, create synonym, create database link, create cluster, createsequence, and alter session. With the release of Oracle 10.2.0.1, only the create session privilegeis granted to the CONNECT role. Oracle removed the additional CONNECT role privileges to provide additionalsecurity by enforcing the principle of least privileges.

The Installer requires the CONNECT role to have both the create session and create table privileges.

To grant the privileges that are required to install Blackboard onOracle 10g, Release 2, log in to the databaseserver as the Oracle user you created, Start SQL*Plus, and execute the following SQL commands:



SQL> commit;

SQL> exit

Confirm AL16UTF16 Character SetThe national alternate character set value for Oracle is AL16UTF16 (also referred to as UTF16). Beforeinstalling the Blackboard software, confirm that the national alternate character set is AL16UTF16.

To determine the National Character Set value, log in to the database server as the Oracle user you created,Start SQL*Plus, and query the v$ table using the following SQL command:



PARAMETER Value

--------------------------------------------- ----------------------------------


Create a Blackboard DatabaseFollow the steps in this section to create a Blackboard Small Scale Oracle 10g database.

To create a Blackboard database:


9.1 S

P6 BETA D

RAFT


1. Log in to the database server as the Oracle user you created.2. In the /usr/local/SSO folder, create a backup copy of the createDatafiles.sql file.3. Open the createDatafiles.sql file and edit the SIZE settings as indicated:

CREATE TABLESPACE "BBADMIN_DATA" LOGGING DATAFILE '$ORACLE_DATA/${ORACLE_SID}_BBADMIN_DATA_data01.dbf'

SIZE 5M AUTOEXTEND ON

EXTENT MANAGEMENT LOCAL AUTOALLOCATE

SEGMENT SPACE MANAGEMENT AUTO;

CREATE TABLESPACE "BB_BB60_DATA" LOGGING DATAFILE '$ORACLE_DATA/${ORACLE_SID}_BB_BB60_DATA_data01.dbf'

SIZE 2000M AUTOEXTEND ON NEXT 50M



CREATE TABLESPACE "BB_BB60_STATS_DATA" LOGGING DATAFILE '$ORACLE_DATA/${ORACLE_SID}_BB_BB60_STATS_DATA_data01.dbf'




CREATE TABLESPACE "BBADMIN_INDX" LOGGING DATAFILE '$ORACLE_DATA/${ORACLE_SID}_BBADMIN_INDX_index01.dbf'

SIZE 5M AUTOEXTEND ON



CREATE TABLESPACE "BB_BB60_INDX" LOGGING DATAFILE '$ORACLE_DATA/${ORACLE_SID}_BB_BB60_INDX_index01.dbf'




CREATE TABLESPACE "BB_BB60_STATS_INDX" LOGGING DATAFILE '$ORACLE_DATA/${ORACLE_SID}_BB_BB60_STATS_INDX_indx01.dbf'




4. Change the shared_pool_size and shared_pool_reserved_sizes to 400 and 200respectively in following three files:/usr/local/SSO/BbInit10g2.ora

/usr/local/SSO/BbInit10g2.ora.template

/usr/local/SSO/init.10g

5. Create the database using the following command:cd /usr/local/SSO

./ BbUpdateSSO.sh

Note: The BbUpdateSSO.sh script runs the createUsersOnUpdate.sql command, whichresults in "ORACLE is not available" errors. You can ignore these errors.

6. Verify your login to the Small Scale Oracle database using the following commands:su – oracle

sqlplus sys/PASSWORD


9.1 S

P6 BETA D

RAFT


Upgrading Small Scale Oracle 9i to 10

Prepare for the UpgradeBlackboard strongly recommends cloning the database and performing a test upgrade on the clone databasebefore updating your production database server. This encourages familiarity with the process without riskingloss or corruption of data.

To prepare the destination database server, complete the Pre-Upgrade Steps for All Servers as well as thesteps for your particular database server:

l Pre-Upgrade Steps for Red Hat Linux Serversl Pre-Upgrade Steps for Solaris Servers

Pre-Upgrade Steps for All ServersBefore upgrading Small Scale Oracle on any database server, perform the steps in this section.

1. Make sure that the database server and application server meet the requirements for your versionof Blackboard software. For the list of requirements, see the Supported Server Configuration pagefor your version in theMaintenance Center, which is accessible through Behind the Blackboard athttps://behind.blackboard.com.

2. Make sure that sufficient disk space is available on the database server. Blackboard recommendshaving at least as much disk space as was required by your previous database as well as enoughdisk space for amanual full backup. This disk space for backups can be offline.

3. Perform a full backup of the Blackboard database.4. Perform a system backup of the database server, including the directory that contains the Oracle

software.5. If they exist, perform a backup of the following folder and file:

/etc/oratab

/etc/oraInst.loc

6. Reboot the system or execute the following command as root:/sbin/sysctl -p

7. Check for invalid objects in the database. If necessary, recompile the objects by running thefollowing command from the $ORACLE_HOME/rdbms/admin folder:@utlrp.sql

8. If they are installed, stop the Blackboard services using the following command:/usr/local/blackboard/tools/admin/ServiceController.sh services.stop

9. Shut down theOracle 9i database using the following command:su - oracle

sqlplus "/ as sysdba"

shutdown immediate;

Pre-Upgrade Steps for Red Hat Linux ServersBefore upgrading Small Scale Oracle on a Red Hat Linux server, perform the following step.

Make sure that the /etc/sysctl.conf file contains the following lines. If it does not, add these lines to theend of the file.

kernel.sem = 250 32000 100 128


9.1 S

P6 BETA D

RAFT



kernel.shmmax = 4294967295

net.ipv4.ip_local_port_range = 1024 65000

net.core.rmem_default = 262144

net.core.rmem_max = 262144

net.core.wmem_default = 262144

net.core.wmem_max = 262144

Pre-Upgrade Steps for Solaris ServersBefore upgrading Small Scale Oracle on a Solaris server, complete the steps in Configuring Kernel Parametersof the Oracle® Database Installation Guide, Preinstallation Tasks section.

Perform the UpgradeThe upgrade process involves installing the Small Scale Oracle database software and then upgrading thedatabase itself using the BbUpdateSSO.sh script.

This script uses the database upgrade assistant to upgrade the existing 9i database files to 10g, and in theprocess creates initSID.ora, spfileSID.ora, and orapwSID files for the new 10g instance. It placesthe old files in a backup directory, but updates everything else in place.

To upgrade the Small Scale Oracle database from 9i to 10g:

1. Install Oracle 10g using the information in Install the Small Scale Oracle 10g Software.

IMPORTANT! Do not complete the steps in Create a Blackboard Database.

2. Log in to Oracle as the Oracle user.3. Upgrade the database using the following commands:

su - oracle

cd /usr/local/SSO

/usr/local/SSO/BbUpdateSSO.sh -b /usr/local/oracle –h

10GPATH -i /usr/local/oracle/9i –k

/usr/local/oracle/dbuabackup9i -s bb_60

Note: The BbUpdateSSO.sh script runs the createUsersOnUpdate.sql command, whichresults in "ORACLE is not available" errors. You can ignore these errors.

4. Set the ORACLE_HOME directory in .profile or .bash_profile to point to the Oracle 10ghome directory using the following command:ORACLE_HOME=10GPATH

5. To update the environment, complete one of the following steps:l Export the variable to your current environment using the following command:

export ORACLE_HOME=10GPATH

-or-

l Source the .bash_profile using the following command:. $HOME/.bash_profile

6. Stop the 9i listener and start the 10g listener using the following commands:kill `ps -ef |grep tnslsnr | grep -v grep | awk '{print $2;}'`

$ORACLE_HOME/bin/lsnrctl start

7. Log in to Oracle as root.


9.1 S

P6 BETA D

RAFT

http://download.oracle.com/docs/cd/B19306_01/install.102/b15697/pre_install.htm#BABGADGE




8. Start the Blackboard services using the following command:/usr/local/blackboard/tools/admin/ServiceController.sh services.start

Note: If the upgrade process fails, execute the following DB Restore Script, and then contactBlackboard support:

su - oracle/usr/local/oracle/dbuabackup9i/bb60_restore.sh

Uninstalling Small Scale OracleTo uninstall Small Scale Oracle:

1. Shut down the database.2. Log in to the database server as root.3. Execute the following commands:

su - oracle

cd 10GPATH

10GPATH/BbUninstallSSO.sh -d /usr/local/oracle/oradata/SSOSID -h 10GPATH -sSSOSID

cd /usr/local/oracle

rm –rf *

exit

cd /usr/local/bin

rm –rf coraenv dbhome oraenv


9.1 S

P6 BETA D

RAFT

Authentication > Using Blackboard Learn Authentication

Authentication

Using Blackboard Learn AuthenticationThe default authentication for Blackboard Learn authenticates the user’s login credentials against theBlackboard Learn database.

Customize the Default AuthenticationChanging the Blackboard Learn Authentication process and options does not require any database changes. Allof the options are stored in a properties file. Modify the authentication.properties file to customize thedefault authentication for Blackboard Learn.

Return to the Default AuthenticationIf, in the Course of setting up a customized Authentication solution, it is necessary to return to BlackboardLearn default authentication (rdbms), the authentication type (bbconfig.auth.type) can be set via thecommand line. This allows Blackboard Learn, at start up, to select the appropriate set of auth.type*.*entries. Follow these steps to reset the system to use the default authenticationmodel:

1. Change to the following directory:cd BB_DEPLOY_DIR\blackboard\config

2. Edit the authentication.properties file as follows:auth.type.rdbms.impl=b-lackboard.platform.security.authentication.BaseAuthenticationModule

auth.type.rdbms.use_challenge=true

3. Edit the bb-config.properties file. Change the bbconfig.auth.type property as follows:bbconfig.auth.type=rdbms

4. Run PushConfigUpdates to activate the changes. To learnmore, see Using Command LineTools.

Authentication PropertiesThe following table describes the available properties for the default authenticationmodel. These properties areconfigured through the authentication.properties file. The authentication.propertiesproperties file is found in blackboard_home/bbservices/config.


auth.type.rdbms.impl Defines the class which must conform to the HttpAuthModule interface. The defaultvalue,blackboard.platform.security.authentication.BaseAuthenticationModule,should not be changed unless the Institution builds and implements its own class forBlackboard Learn default authentication.

auth.type.rdbms.use_challenge

Defines the encryption setting where a value of false indicates the password isencrypted with base 64 and a value of true indicates the password is encrypted withMD5. The default value is true. MD5 encryption offers stronger security for passwords.Base64 is similar to sending the password in plain text.


9.1 S

P6 BETA D

RAFT

Authentication > About Authentication Object Models

About Authentication Object ModelsThere are three objects used in Blackboard’s default authentication type:

l HttpAuthManager

l HttpAuthModule

l BaseAuthenticationModule

The HttpAuthManager class and the HttpAuthModule interface cannot bemodified. Institutions can plug-in their ownmodule for a supported authentication type.

Authentication Object ModelThe BaseAuthenticationModule class implements the HttpAuthModule interface and supports thedefault authentication type. The following object model depicts the HttpAuthModule implementations forLDAP andWeb server delegation. IIS Web server delegation support is implemented in the classWindowsAuthModule. ApacheWeb server delegation support is implemented in the classExternalAuthModule.

Note: Although WindowsAuthModule are public Java classes, it is not permitted to extend these classes.Most authenticationmodules will extend BaseAuthenticationModule. The PassportAuthModule isnot supported in Release 7.0 and higher.

Planning Authentication ImplementationThis topic includes information on how the different authentication types (Blackboard default authentication,LDAP, andWeb server delegation) are implemented. This informationmay be helpful to developers creating acustom authentication for Blackboard Learn.

Blackboard Default ImplementationThe default implementation (realized in the class BaseAuthenticationModule) is implemented as achallenge response protocol, using a form submitted by HTTP-POST. This is amechanism that avoidssending the actual password over the network in an unprotected fashion. In a naïve authenticationimplementation, username/password combinations would simply be transmitted across the network in cleartext. The problem with this method is that malicious users would be able to see the username and password.

To facilitate greater security the authentication framework generates a pseudo-random number for eachauthentication attempt that is MD5-hashed against the servlet engine’s session ID. This “challenge” string issent to the client. The challenge string increases system security by improving the chances that thetransmitted code has not been tampered with. When the user enters their password, it is MD5-hashed, thenthat hash string is combined with the challenge string sent by the server, and the resulting string is MD5-hashed. The resulting string is cryptographically secure in that the hash is one-way (MD5). This means that it isnot possible to reconstruct its inputs, or to find inputs that result in the same hashed value. This compoundhash is called the “response.”

The server, when it receives the client response, performs the same calculations the client performed (excepton the server-side, the password is already hashed). Additionally, the challenge string is also re-calculated fromthe stored pseudo-random number (to help prevent session hijacking). If the results match the client response,the authentication is successful.


9.1 S

P6 BETA D

RAFT

Authentication > Planning Authentication Implementation

LDAP ImplementationBlackboard has implemented a simple LDAP authenticationmodule that uses data from theauthentication.properties configuration file to bind to an LDAP server, or series of LDAP servers, andperform a lookup of a given user. To learnmore about the configuration settings for LDAP authentication, seeSetting Up LDAP Authentication Properties.

Web Server Delegation ImplementationBlackboard has implemented aWindows-specific Web server delegation authenticationmodule that assumesthe installation of a Blackboard-created ISAPI filter on theWeb server; the ISAPI filter populates a requestheader containing the Active Directory username for theWindows user. The WindowsAuthModuleauthenticationmodule parses the request, extracts the unique identifier and attempts tomatch that identifier toa user in Blackboard Learn database.

WindowsAuthModule’s parent class, ExternalAuthModule, is a simple, general implementation forWebserver-delegated authentication. It assumes that amodule or filter has been installed on theWeb server thatpopulates the Computer Gateway Interface (CGI) variable REMOTE_USER in the request headers.

Extending Other Blackboard-created Authentication ModulesExtending other Blackboard-created implementations such as WindowsAuthModule is not permitted at thistime.

Sample Custom Authentication ModuleThe following is an example of a Custom AuthenticationModule:

package blackboard.authentication.test;

import javax.servlet.http.HttpServletRequest;

import javax.servlet.http.HttpServletResponse;

import blackboard.platform.BbServiceManager;

import blackboard.platform.RuntimeBbServiceException;

import blackboard.platform.config.ConfigurationService;

import blackboard.platform.log.LogService;

import blackboard.platform.security.authentication.BaseAuthenticationModule;

import blackboard.platform.security.authentication.BbAuthenticationFailedException;

import blackboard.platform.security.authentication.BbCredentialsNotFoundException;

import blackboard.platform.security.authentication.BbSecurityException;

import blackboard.platform.security.authentication.HttpAuthConfig;

import blackboard.platform.security.authentication.SessionStub;

/**

* @author Blackboard Development

*

* A Sample Custom Authentication Module.


9.1 S

P6 BETA D

RAFT


*/

public class CustomAuthModule extends BaseAuthenticationModule {

//Save the log service so that we can log events.

private LogService _logger;

/*

* Module initialization. This method gets called when Tomcat starts up.

*/

public void init(ConfigurationService arg0) throws

IllegalStateException {

//Although this is not necessary for subclasses of

//BaseAuthenticationModule, it is a good practice to do this

//unless there is a reason not to.

super.init(arg0);

try {

// Set up logging

_logger = BbServiceManager.getLogService();

} catch (RuntimeBbServiceException e) {

e.printStackTrace();

}

if (_logger == null) {

//This println statement will output to the

//stdout-stderr.log file.

System.out.println("logger is null");

} else {

_logger.logWarning("Custom Auth Module: init()");

}

}

/*

* Does the work of authenticating the user.

*/

public String doAuthenticate(

HttpServletRequest request,

HttpServletResponse response)

throws BbSecurityException,

BbAuthenticationFailedException,

BbCredentialsNotFoundException {

//Since this module uses the standard Learn login form,

//use the superclass implementation. The authenticated() method is then

//overridden to customize behavior. Other authentication modules

//could do something else here if needed, as long as the

//userid is returned or an exception is thrown.

_logger.logWarning("Custom Auth Module: doAuthenticate()");


9.1 S

P6 BETA D

RAFT


return super.doAuthenticate(request, response);

}

/*

* Gets called when the user explicitly logs out.

*/

public void doLogout(



throws BbSecurityException {

_logger.logWarning("Custom Auth Module logging out");

//perform custom logout work here

}

/*

* Gets called when the user needs authenticating.

*/

public void requestAuthenticate(




//Do the superclass implementation, redirect to the Default Login

//Page

_logger.logWarning("Custom Auth Module: requestAuthenticate()");

super.requestAuthenticate(request, response);

}

/*

* Returns a String containing the authentication type.

*/

public String getAuthType() {

return "custom";

}

/*

* Returns a String array of properties used by this authentication

* type.

*/

public String[] getPropKeys() {

String[] props = {"impl", "prop1"};

return props;

}


9.1 S

P6 BETA D

RAFT


/*

* Blackboard Learn calls this to hand the authentication module the

* configuration properties. This gets called before init so that it can

* use its properties if needed.

*/

public void setConfig(HttpAuthConfig config) {

//Just use BaseAuthenticationModule implementation. It will set

//the member variable _config. Most modules that extend

//BaseAuthenticationModule need not override this method.

super.setConfig(config);

}

/*

* Overrides BaseAuthenticationModule to do something different.

*/

protected String authenticate(

String username,

String password,

SessionStub sessionStub,

boolean useChallenge)

throws BbAuthenticationFailedException,

BbSecurityException {

//Do authentication logic here; validate password against an external

//source... Could also call the superclass implementation to "fall

//back" to Blackboard.

//This implementation just tries out the exceptions that can be

//thrown.

if (username.equals("error1")) {

throw

new BbAuthenticationFailedException("Custom auth module, error1.");

}


throw new BbSecurityException("Custom auth module, error2.");

}


//null parameters, should display standard message.

throw new BbAuthenticationFailedException();

}

//otherwise, return the user passed without checking. The user must

//exist in Blackboard Learn for this to work properly.


9.1 S

P6 BETA D

RAFT

Authentication > About Active Directory Authentication

return username;

}

} //End CustomAuthModule

Sample IUserPassAuthModule CodeYou need to implement IUserPassAuthModule in a custom authenticationmodule and add thegetUserFromUsernamePassword(x,y)method as follows:

public class CustomAuthModule extends BaseAuthenticationModule

implements IUserPassAuthModule{

public User getUserFromUsernamePassword(String username, String

password)

throws PersistenceException, BbAuthenticationFailedException,

BbSecurityException {

// Required when implementing IUserPassAuthModule

// IUserPassAuthModule is necessary to ensure

compatibility with Content System (WebDAV)

String validatedUsername = authenticate(username,

Base64Codec.encode(password), null, false);

if (validatedUsername == null)

return null;

User user;

try { user = UserDbLoader.Default.getInstance().loadByUserName(validatedUsername); }catch (KeyNotFoundException e) { return null; } catch (Exception e) { return null; } }

return user;

}

}

About Active Directory AuthenticationBlackboard Learn supports Web server delegated authentication. It includes aWeb server filter for ActiveDirectory that will authenticate users against an Institution’s Active Directory server. All the files necessary tosupport Active Directory authentication are included with Blackboard Learn.

Active Directory AuthenticationMicrosoft® Active Directory™ is a part of theMicrosoft® Windows® network architecture and is intended asan enterprise-level integration. It allows Organizations to share andmanage information about networkresources and users. In addition, Active Directory acts as the central authority for network security, letting theoperating system verify a user's identity and control his or her access to network resources, such as data,applications, or printers. There are a number of benefits to using Active Directory. Administrators have a singlepoint of management forWindows-based user accounts, clients, servers, and applications. Active Directoryauthentication also allows for standardized business rules for applications and network resources.


9.1 S

P6 BETA D

RAFT

Authentication > Setting Up Active Directory

Security ConsiderationsWhen the Active Directory authentication is implemented a user has a single Microsoft Windows User ID and asingle Blackboard Learn User Name. The database has a single entry for this user. The level of security for theWindows User ID and password is the same as that for Blackboard Learn User Name and password.

When users are working on a shared computer they must close the browser and log out of Windows at the endof the session to ensure their security in maintained.

LimitationsThe user’s Blackboard Learn User Name is associated with their Microsoft Windows’ login. This means thatthe user’s database record is linked to theirWindows User Name and password allowing them to only have oneBlackboard Learn User Name. For example, Windows user “jdoe” can only have one Blackboard Learn login; heor she cannot be "Instructor1" and "Student2" in Blackboard Learn.

To ensure the safety of user accounts, the browser must be closed and the user must log off of Windows whena session on a shared computer is ended.

For questions about these limitations, contact Blackboard Technical Support by logging in to Behind theBlackboard at https://behind.blackboard.com.

Active Directory Authentication and Portal Direct EntryBlackboard does not currently support usingWeb Server Delegation with Portal Direct Entry. Clients whowould like to set up a customized authentication withWeb Server Delegation and Portal Direct Entry shouldcontact Blackboard Global Services.

Setting Up Active DirectoryThe properties set for Active Directory authentication are found in the auth.type.webserver section of theauthentication.properties file.

Note: There is no special configuration needed for IIS.

File FormatThe authentication.properties file contains a series of properties that must be set beforeauthentication against the Institution’s Active Directory server or servers can occur. Each property is listed withan equal sign followed by the corresponding value.

How to Set the Authentication TypePrior to editing the authentication.properties file, the authentication type (bbconfig.auth.type)must be edited in the bb-config.properties file. This allows Blackboard Learn to select the appropriateset of auth.type*.* entries at start up. The following steps are instructions for setting the authentication toActive Directory.

1. Edit the authentication.properties file.2. Edit the bb-config.properties file so that bbconfig.auth.type=webserver.3. Run PushConfigUpdates to activate the changes. To learnmore, see PushConfigUpdates.


9.1 S

P6 BETA D

RAFT


Authentication > Setting Up Active Directory

4. IIS only: Run theWebsite Reinstaller tool to remove and reinstall IIS: blackboard_home\tools\admin\WebsiteReinstall.bat

In the IIS Management Console for Blackboard Learn, select the authenticationmethod or methods.The options are Basic, Digest, and IntegratedWindows authentication. One or more options may beselected.

Note: All custom changes to IIS will be removed after running this tool. For example, configurations to IIS tosupport SSL Choice will be erased.

Active Directory Property ConfigurationThe table below details the properties configured through the authentication.properties file.


auth.type.webserver.impl=blackboard.platform.security.authentication.WindowsAuthModule

Defines the class which must conform to the HttpAuthModule interface. Thedefault value,blackboard.platform.security.authentication.WindowsAuthModule,should not be changed unless the Institution builds and implements its ownclass for Web Server Delegation authorization.If using Kerberos or another type of Web Server Delegation and it is configuredto set the standard REMOTE_USER header then useblackboard.platform.security.authentication.ExternalAuthModule.

auth.type.webserver.user_account Describes how external users are handled by Blackboard Learn. It is set toreconcile, create or deny. The first thing the system does for any of thesesettings is check for an existing user account that is associated with the externalUser ID. If one is not found, the following will occur:

l If set to reconcile the system will display a page that allows the userto login as an existing Blackboard user once, associate thatBlackboard user account with the external user ID, and then will logthem in via Web server delegated authentication in the future.

l If set to create, the system will try and create a new user account withminimal information that has to be updated by the user orAdministrator. The user name is automatically webserver-user-usernumber (for example, webserver-user-100).

l If set to deny, a message will be displayed for the user to contact theAdministrator.

auth.type.webserver.suppress This property, if set to true hides the login form fields. This should be usedwhen an external authority is the only place where passwords should beentered, as is standard with web-based authentication.

ExampleThe example below details the properties configured forWeb server delegation through theauthentication.properties file. The example uses reconcile to handle external users. Create and Denyare also valid options for this property.

auth.type.webserver.impl=blackboard.platform.security.authentication.WindowsAuthModule

auth.type.webserver.user_account=reconcile

auth.type.webserver.suppress=true


9.1 S

P6 BETA D

RAFT

Authentication > About the LDAP Authentication Module

About the LDAP Authentication ModuleStandard LDAP (Lightweight Directory Access Protocol) authentication is fully integrated with BlackboardLearn. All necessary .jar files, including those for setting up an SSL connection between Blackboard Learnapplication server and the directory servers, are provided in the /systemlib directory. The application serverstartup executables include the .jar files in their classpath. Note that all configuration options in theauthentication.properties file are set to default values. Some of these default values are place holdersandmust be changed by the Administrator for LDAP authentication to work successfully.

To begin authenticating against an LDAP server or servers, set the properties found in theauthentication.properties file. The SSLConfiguration topic has specific information on enabling theBlackboard Learn application server and the directory servers to communicate over SSL.

LimitationsThe limitations of this version of the LDAP module are summarized in the following list.

l Themodule only supports authentication through a successful bind with the directory server using theFDN for this Blackboard user—themodule cannot retrieve any information from the directory.

l Themodule only supports binding anonymously or binding with a privileged user and then performinga search for the user's FDN.

Check with Blackboard Technical Support if you have any questions regarding these limitations.

For installation problems or questions while using this document, contact Blackboard Technical Support bylogging in to Behind the Blackboard at https://behind.blackboard.com. For planning, architectural analysis, bestpractices, or assistance with implementation, call Blackboard Technical Solutions.

LDAP AuthenticationLDAP is an Internet standard that provides access to information from different computer systems andapplications. LDAP uses a set of protocols to access information directories and retrieve information. Adirectory is like a database, but contains information that is more descriptive and attribute-based. Information ina directory is generally readmore often than it is written or modified. LDAP allows an application, running on theInstitution’s computer platform, to obtain information such as user names and passwords.

Centralizing this type of information is very beneficial. It simplifies the job of the administrator by providing asingle point of administration. It also provides a single location for user information, reducing the storage ofduplicate information. This, in turn, reduces maintenance needs. LDAP authentication also enables users tohave a single login and password to access a number of different applications.

Setting Up LDAP Authentication PropertiesThe properties set in the authentication.properties file include general properties for LDAPconfiguration, as well as properties for individual directory servers. When addingmultiple servers the variable xrepresents the sequence number. Parameters must be set for each directory server that Blackboard Learn willauthenticate against. The LDAP module will access the servers according to the sequence number.

File FormatThe authentication.properties and bb-config.properties files contain a series of properties thatmust be set before authentication against the Institution’s directory server or servers can occur. Each property


9.1 S

P6 BETA D

RAFT


Authentication > Setting Up LDAP Authentication Properties

is listed with an equal sign followed by the corresponding value.

How to Edit the Authentication Properties FileOpen the authentication.properties file in an editor and set the LDAP specific properties tomatch theInstitution. Descriptions of the properties appear in the following section.

Properties that are suffixed with a number are properties that are associated with an individual directory server.To add information for additional directory servers, add a group of properties suffixed with the next availablesequence number. The LDAP module will access the servers in the order in which they are sequenced.

LDAP Property ConfigurationThe table below details the LDAP properties configured through the authentication.properties file.


auth.type.ldap.impl Defines the class which must conform to the HttpAuthModule interface. The default value,blackboard.platform.security.authentication.LDAPAuthModule, should not be changedunless the Institution builds and implements its own class for LDAP authorization.

auth.type.ldap.use_challenge

Defines the encryption setting where a value of false indicates base 64 encryption and a value oftrue indicates MD5 encryption. The default value is false. MD5 encryption should only be used ifthe LDAP servers use MD5 encryption in the same manner as Blackboard. In most cases, using base64 encryption and securing the connection between Blackboard Learn and the LDAP servers withSSL is the best approach.

auth.type.ldap.num_servers

Defines the number of directory servers in use. For each server, there must be a corresponding set ofserver properties. This property must be kept current; update it each time a new server’s entries areadded to the authentication.properties file.

auth.type.ldap.user_not_found_fallback

Can be set to true or false. By default, this property is set to falsebecause of the securityconsiderations outlined in LDAP Security Considerations. If set to true, the module will attempt toauthenticate the user using the password in Blackboard Learn database if the user is not found inany of the directory servers.

auth.type.ldap.error_fallback_to_bb

Can be set to true or false. By default, this property is set to false because of the securityconsiderations outlined in LDAP Security Considerations. If set to true, the module will attempt toauthenticate the user using the password in Blackboard Learn database if there is an errorconnecting to any of the directory servers.

Server Specific Properties

auth.type.ldap.server_url.x

The URL of the directory server including port.Example: ldap://directory.university.edu:389If the LDAP server is setup to communicate over SSL, the URL should be:ldaps://directory.university.edu:636.

auth.type.ldap.server_ssl.x

Must be set to true or false. If set to true, the module will attempt to connect to the LDAP directoryusing SSL. The LDAP server must be set up to handle SSL connections. To learn more, see AboutSSL and SSL Choice.

auth.type.ldap.use_priv_user.x

Must be set to true or false. If set to true, the module will bind to the LDAP server as a privileged(specific) user when searching for the FDN of the user to authenticate.

auth.type.ldap.user_fdn.x The user binds as this FDN. Leave as (none) if not applicable.

auth.type.ldap.user_pwd.x The password of the privileged user. Leave as “(none)” if not applicable.


9.1 S

P6 BETA D

RAFT

Authentication > Setting Up LDAP Authentication Properties


auth.type.ldap.deref_aliases.x

Set this property to configure how aliases are dereferenced during search operations. The followingvalues are defined for this property:

l always: Always dereference aliases.l never: Never dereference aliases.l finding: Dereference aliases only during name resolution (that is, while locating the

target entry).l searching: Dereference aliases once name resolution has been completed (that is, after

locating the target entry).

auth.type.ldap.user_tag.x Set this property to the attribute containing Blackboard Learn User Name. This setting is domainspecific.

auth.type.ldap.server_error_fatal.x

Must be set to true or false. If set to true, the module will exit with a fatal error if there is an errorconnecting to the server.

auth.type.ldap.context_factory.x

Set this property to handle password expiration warnings for LDAP accounts. The following valuesare defined for this property:

l black-board.platform.security.authentication.PasswordPolicyContextFactory forIETF-compatible LDAP servers (Novell, Active Directory). This is the default value.

l black-board.platform.security.authentication.ResponsePolicyContextFactory forNetscape-compatible LDAP servers supporting the Netscape response controlspecification.

auth.type.ldap.referral.x The value of this property is a string that specifies how referrals should be handled by the module.The following values are defined for this property:

l follow: Automatically follow any referrals.l throw: Throw a Java ReferralException for each referral. This will result in an error

condition for this server.l ignore: Ignore referrals if they appear in results. In debug mode, a log message will be

generated to indicate an incomplete result, but this will not result in an error condition forthis server.

auth.type.ldap.referral_limit.x

The value of this property is a string of decimal digits specifying the maximum number of referrals tofollow in a chain of referrals. A setting of zero indicates that there is no limit.

base_search_fdn The starting point in the LDAP directory structure for searching for a Blackboard Learn user.

ExampleThe following is an example of the LDAP properties configured through the authentication.propertiesfile.

auth.type.ldap.impl=blackboard.platform.security.authentication.LDAPAuthModule

auth.type.ldap.use_challenge=false

auth.type.ldap.error_fallback_to_bb=false

auth.type.ldap.user_not_found_fallback_to_bb=false

auth.type.ldap.log_level=error

# Available property values for auth.type.ldap.log_level arefatal,error,warning,information,debug

auth.type.ldap.num_servers=2

# The auth.type.ldap.num_servers property value must be increased with each serverconfiguration addition. If there are three server configurations, then the value must be3 for this parameter.


9.1 S

P6 BETA D

RAFT

Authentication > Using LDAP Authentication Fail Over

Server #1 Configurationauth.type.ldap.server_ssl.1=false

# The auth.type.ldap.server_ssl property value sets SSL interaction between # theBlackboard installation server and LDAP server to true or false.

auth.type.ldap.base_search_fdn.1=dc=dc,dc=blackboard,dc=com

auth.type.ldap.deref_aliases.1=never

auth.type.ldap.server_url.1=ldap://lsvr1

auth.type.ldap.use_priv_user.1=true

auth.type.ldap.user_fdn.1=uid=UserA,ou=Special Users,dc=dc,dc=blackboard,dc=com

auth.type.ldap.user_pwd.1=test1

auth.type.ldap.user_tag.1=uid

auth.type.ldap.referral.1=ignore

auth.type.ldap.referral_limit.1=0

auth.type.ldap.server_error_fatal.1=true

auth.type.ldap.context_factory.1=blackboard.platform.security.authentication.PasswordPolicyContextFactory

Server #2 Configurationauth.type.ldap.server_ssl.2=false

# The auth.type.ldap.server_ssl property value sets SSL interaction between # theBlackboard installation server and LDAP server to true or false.

auth.type.ldap.base_search_fdn.2=dc=dc,dc=blackboard,dc=com

auth.type.ldap.deref_aliases.2=never

auth.type.ldap.server_url.2=ldap://lsvr2

auth.type.ldap.use_priv_user.2=true

auth.type.ldap.user_fdn.2=uid=UserB,ou=Special Users,dc=dc,dc=blackboard,dc=com

auth.type.ldap.user_pwd.2=test2

auth.type.ldap.user_tag.2=uid

auth.type.ldap.referral.2=ignore

auth.type.ldap.referral_limit.2=0

auth.type.ldap.server_error_fatal.2=true

auth.type.ldap.context_factory.2=blackboard.platform.security.authentication.PasswordPolicyContextFactory

Using LDAP Authentication Fail OverAdministrators must determine how Blackboard Learn should function if the directory servers are notfunctioning correctly at the time of an authentication request or if a user who does not exist in the LDAPdatabase attempts to login to Blackboard Learn.

Automatic authentication fail over may be set for one or both of the following properties:

auth.type.ldap.error_fallback_to_bb

auth.type.ldap.user_not_found_fallback

Automatic fail-over functionality poses certain security risks that are discussed below in SecurityConsiderations.


9.1 S

P6 BETA D

RAFT

Authentication > Using LDAP Authentication Fail Over

Note: The behaviors listed in the Troubleshooting LDAP Scenarios do not apply if the default configuration ischanged.

Automatic Fail Over for LDAP Server ErrorLDAP authentication is intended as an enterprise-level integration; therefore, the expectation is that the LDAPserver will bemanaged administratively as amission-critical system. The LDAP interface was developed todepend upon the constant availability of the directory servers.

Automatic fail over in the case of LDAP server error enables Institutions that are not supporting LDAP as amission-critical system to allow users access to the system if the LDAP server fails. Automatic authenticationfail over will allow Blackboard Learn to continue to run in the event that the LDAP server or servers do notfunction correctly. In this instance, automatic fail over is set for the auth.type.ldap.error_fallback_to_bb property.

Automatic Fail Over for Users who Do Not Exist in LDAP DatabaseThis fail over option allows users who do not exist in the LDAP database to log into Blackboard Learn.Examples are administrators, users, or students who are auditing, but are not enrolled, in a class. In thisinstance, automatic fail over is set for the auth.type.ldap.user_not_found_fallback property.

Security ConsiderationsAutomatic authentication fail over has some additional security considerations:

l Passwords are not synchronized: Blackboard Learn will not know the passwords in LDAP, soAdministrators have to keep track of separate passwords.

l Security back doors: Automatic fail over for authenticationmay introduce serious security problemsnot related to Blackboard Learn. For example, if a user attempted a denial of service (DOS), theycould shut down the directory server and attempt to log in with default passwords, which is the username.

Synchronizing user data between the LDAP servers and Blackboard Learn (via Snapshot or the Event DrivenAPIs) can prevent failover from using default passwords and also enable failover to require the same password as the normal LDAP authentication.

How to Enable Authentication Fail Over for LDAP Server Error1. Set the authentication property auth.type.ldap.error_fallback_to_bb to true.2. Populate Blackboard Learn database with correct username and password information.3. Restart the application server.

To learnmore, see LDAP Property Configuration.

How to Enable Authentication Fail Over for Users who Do Not Exist inLDAP Database

1. Set the authentication property auth.type.ldap.user_not_found_fallback to true.2. Populate Blackboard Learn database with correct username and password information.3. Restart the application server.

To learnmore, see LDAP Property Configuration.


9.1 S

P6 BETA D

RAFT

Authentication > Using LDAP with Active Directory

Using LDAP with Active DirectoryAdministrators may decide to use Active Directory via LDAP. This may be done by connecting to ActiveDirectory via an anonymous bind or by using a privileged user. The following topic explains how to set up ananonymous connection or a privileged connection, and some accompanying security risks.

Connecting via an Anonymous BindActive Directory does not allow anonymous access by default, but Administrators may enable anonymoussearches if they choose.

Note: There are security risks with allowing anonymous LDAP binds with Active Directory; in this case, anyusers who have network access to the Active Directory server can search Active Directory.

How to Enable Anonymous Searches on the Active Directory Server1. On theWindows 2000 Active Directory server, run the Active Directory Users andGroups

administration tool.2. Select the top level of the directory from the tree view in the left hand panel, and right click. Select

the first item on themenu, which begins withDelegate Control. Click Next.3. In the next window, titledUsers or Groups, click Add.4. On the next list, select ANONYMOUS LOGON and click Add. Administrators may also need to

select Everyone and theGuests group, depending on how Active Directory is configured. ClickOK when this is done. Click Next.

5. Select Create a custom task to delegate and click Next.6. In the next list, select Read. Read All Propertieswill be selected at the same time. Click Next.7. Click Finish.

Connecting via a Privileged BindBy default, Active Directory can only be searched via LDAP if a privileged user is used to connect to the LDAPserver. A privileged bind requires the distinguished name (DN) and password for the user. There are two optionsfor connecting via a privileged bind:

l Create a new Windows user within Active Directory. Assign this user only the right to read access tothe directory. Use this user as the privileged user.

l Use an existingWindows user as the privileged user.

Note: There are security risks with connecting via a privileged bind to Active Directory. Any user who cannavigate to the file system and locate the authentication.properties file may find the user ID andpassword of the privileged user.

Troubleshooting LDAP with Active DirectoryFor Administrators using aWindows workstation, the LDP executable may be used to troubleshoot LDAPauthentication properties. The LDP executable, found on theWindows 2003 Server CD in the\SUPPORT\TOOLS folder, allows LDAP operations to be performed against Active Directory and includes agraphical user interface. To learnmore, see Troubleshooting LDAP.


9.1 S

P6 BETA D

RAFT

Authentication > Troubleshooting LDAP

The only change for this procedure is in Steps 2, 10 and 12. Follow the steps below when using the LDPexecutable against Active Directory:

1. Login as theWindows user (username, password, domain) whose username and password arebeing used for the privileged bind.

2. Add sAMAccountName to theAttributes field and click OK.3. Enter (sAMAccountName=WindowsUserName) in the Filter field, where WindowsUserName

is theWindows username that will be used as the privileged user for binding to LDAP.

For Administrators using a UNIX workstation, the LDAP Browser may be used to troubleshoot LDAPauthentication properties. To learnmore, see Troubleshooting LDAP.

Troubleshooting LDAPThe LDAP module should function with minimal maintenance if the authentication.properties file isconfigured properly. This topic includes information on how to troubleshoot configuring the properties files andonmaintenance for LDAP authentication.

How to Debug LDAP AuthenticationAdministrators may debug the LDAP authentication as part of troubleshooting.

1. In the /blackboard.config/service-config.properties file,under LoggingService, make the following change:blackboard.service.log.param.logdef.default.verbosity=debug

2. Restart the following services:/blackboard_home/tools/admin/ServiceController services.stop

/blackboard_home/tools/admin/ServiceController services.stop

3. Login to the system again.4. Search /blackboard_home/logs/bb-services-log.txt for references to

LDAPAuthModule.

Windows: Open the log file in a text editor and search for LDAPAuthModule.

UNIX: Execute the following: tail -f -n200 /blackboard_home/config/service-config.properties | grep "LDAPAuthModule"

Troubleshooting LDAP Authentication Properties for WindowsFor Administrators using aWindows workstation, the LDP executable may be used to troubleshoot LDAPauthentication properties. The LDP executable, found on theWindows 2003 Server CD in the\SUPPORT\TOOLS folder, is used to search for specific data against the Active Directory and includes agraphical user interface. For users not using Active Directory, this tool may be used in the sameway againstother LDAP servers.

How to Use the LDP Tool1. Go to theConnectionmenu, uncheck theNTLM/Kerberos check box, and select Bind.2. Enter the LDAP privileged user DN in theUser field and the LDAP password in thePassword field.3. Locate the defaultNamingContext attribute.4. Go to theViewmenu and select Tree.


9.1 S

P6 BETA D

RAFT


5. Type the defaultNamingContext attribute value into theBaseDN field and click OK.6. Locate the container for user records. By default, the DN for this container starts with CN=Users.

However, the user records may be located elsewhere. Try to locate the DN that contains all facultyand student user records.

7. Record the DN that contains all faculty and student user records.8. Double-click on the tree view of this container to see all user records.9. Go to theOptionsmenu and select Search.10. Customize fields in the user records returned from the search. (This stepmay not be necessary)11. With the container selected, go to theBrowsemenu and select Search.12. Enter the user field to search by. The user field is the user tag property, for example, (CN=jsmith).13. Record the distinguishedName attribute for this user record.14. Verify that you can find a sample user. Type the baseDN from Step 7 and (user_

tag=someUserValue) where user_tag is the name of the LDAP user record field that the clientexpects users to enter in the Blackboard login form. (For example, if the client expects users tologin by entering their email address as the ‘username’ in the Blackboard login form, then the user_tag should be the name of the field that stores the user’s email address).

15. Update the authentication.properties file:

Set auth.type.ldap.base_search_fdn.1 to the DN for the container for user records (SeeStep 7).

Set auth.type.ldap.user_fdn.1 to the distinguishedName attribute value for the LDAP user(See Step 13).

Windows only: If the client wants users to login to Blackboard using aWindows username, setauth.type.ldap.user_tag.1 to sAMAccountName. sAMAccountName is the name of theActive Directory user record field that stores theWindows username.

Troubleshooting LDAP Authentication Properties for UNIXFor Administrators using a UNIX workstation, the LDAP Browser may be used to troubleshoot LDAPauthentication properties. This tool may be found at http://www.iit.edu/~gawojar/ldap/.

How to Use the LDAP Browser1. Open the LDAP browser.2. Click File Menu and select Connect.3. Enter the LDAP server hostname in theHost field.4. Enter the port number that the LDAP server is listening on in thePort field.5. Enter the base search DN in theBase DN field. If a privileged bind is required, uncheck

Anonymous bind.6. Type the privileged user DN in theUser DN field. If Append base DN is checked, the

Administrator only needs to add the relative DN ( for example, if the base DN is "OU=test

users,dc=blackboard,dc=com" and the privileged user's full DN is"CN=privldap,OU=ldap testers,OU=test users,dc=blackboard,dc=com", thenenter only "CN=privldap,OU=ldap testers").

7. Click Connect.8. Click Search to search for a given user DN, or scroll through the list.


9.1 S

P6 BETA D

RAFT

http://www.iit.edu/~gawojar/ldap/


How to Revert to Default AuthenticationTo revert to the default authentication from LDAP, change bbconfig.auth.type to "rdbms”, and restartBlackboard Learn application server.

Blackboard Application LogBlackboard Learn log records all application events handled by the Java API. Within the log the BlackboardLDAP module writes error, warning, informational, and debugmessages to the bb-services-log.txt file.

Common ProblemsThe following table outlines some of the common problems that may occur when authenticating BlackboardLearn users against LDAP servers.

Problem Action

The LDAP module loads but users cannot login using their LDAP passwords.

Ensure that all of the users logging in have a Blackboard LearnUser Name. Blackboard Learn needs a user record to associateCourse and other information to the user.

An error is posted to the bb-services-log.txt whenever a user tries to log into thesystem. The module is configured to use SSL.

Ensure that the server certificate for your LDAP directory has beenimported into the keystore of the JVM on Blackboard Learnapplication server. The JVM needs this certificate to allow SSLconnections to the LDAP directory.

The LDAP module loads, but users cannot login. Nothing is displayed in the logs, or themessages that are displayed are insufficient todiagnose the problem.

Re-run the auth-type.properties file and specify a log_level of “debug”. Log messages will generate with more detail.

LDAP ScenariosThe following table details the systems response to a number of potential LDAP situations. The defaultconfiguration of LDAP will support the set of behaviors described here.

Issue Symptom

The LDAP server isdown

Authentication should fail with an appropriate message.

The user exists inBlackboard but notin LDAP


The user exists inLDAP but not inBlackboard


The privileged userdoesn't exist or hasexpired

Authentication should fail with an appropriate message. Blackboard Learn configuration filemust be updated to proceed.

The privileged userpassword haschanged

Authentication should fail with an appropriate message. Blackboard Learn configuration filemust be updated to proceed.


9.1 S

P6 BETA D

RAFT


Issue Symptom

There are multipleLDAP accounts fora specific user

The search domain would be restricted to a specific context within the directory tree. The firstaccount returned will be the one used. It is the Institution's responsibility to set the base_search_fdn property correctly to avoid this situation.

The LDAP SSLcertificate expires

Authentication should fail with an appropriate message. The LDAP SSL certificate must beupdated to proceed.

How to Troubleshoot LDAP with SSLThis section explains how to troubleshoot the SSL connection between the Blackboard server and the LDAPserver for clients who are using an SSL connection to secure their LDAP server.

1. Save /blackboard_home/apps/tomcat/bin/tomcat.sh as tomcat.sh.prod.2. Enter the following command: cp tomcat.sh.prod tomcat.sh.debug.3. Insert -Djavax.net.debug=all,record,plaintext into tomcat.sh.debug.4. Go to line 207 of tomcat.sh.debug. Edit this line to read as follows:

$JAVACMD -Djavax.net.debug=all,record,plaintext $TOMCAT_OPTS $JAVA_OPTS $MAINstart $@ \

5. Enter the following command: cp tomcat.sh.debug tomcat.sh.6. Restart services.7. Login with the LDAP username and password.8. Copy the SSL-connection trace information from /usr/local/blackboard/logs/tomcat-

jvm-stdout.txt. See the log file example below.9. Repeat Steps 6 and 7 until debugging is complete.10. Enter the following command: cp tomcat.sh.prod tomcat.sh.11. Restart services.

Follow these instructions for debugging and clean up onWindows:

1. Save D:\blackboard_home\apps\tomcat\conf\jk\wrapper.properties aswrapper.properties.prod.

2. Copy wrapper.properties.prod and name the copy wrapper.properties.debug.3. Insert -Djavax.net.debug=all,record,plaintext into wrapper.properties.debug.4. Go to line 163 of wrapper.properties.debug.5. Edit that line to read as follows:

"wrapper.cmd_line=$(wrapper.javabin) $(wrapper.java_opts) -Djavax.net.debug=all,record,plaintext -Djava.security.policy=="$(wrapper.tomcat_policy)" -Djava.security.manager -Dtomcat.home="$(wrapper.tomcat_home)" -Dblackboard.home="$(bbapp.root)" -Dbbservices_config="$(bbapp.root)\config\service-config.properties" -Dorg.apache.tomcat.apps.classpath="$(wrapper.class_path.apps)" -classpath$(wrapper.class_path) $(wrapper.startup_class) -config $(wrapper.server_xml)"

6. Delete wrapper.properties, and then copy wrapper.properties.debug and name thecopy wrapper.properties.

7. Restart services.8. Login with the LDAP username and password.9. Copy the SSL-connection trace information from D:\blackboard\logs\tomcat-jvm-

stdout.txt. See the log file example below.10. Repeat until debugging is complete.


9.1 S

P6 BETA D

RAFT


11. Delete wrapper.properties, and then copy wrapper.properties.prod and name thecopy wrapper.properties.

12. Restart services.

Log File ExampleIf the SSL -connection-setup process cannot continue, the reason for the SSL connection setup failure isprinted to the tomcat-jvm-stdout.txt log. After this failure appear in the log the SSL-debug output stops. Thereare a number of reasons why the application server may have trouble connecting to the LDAP server over SSL.The problem can be found in the SSL-debug output. Open the tomcat-jvm-stdout.txt log; go to the end of thedebug output (where it gives the reason for quitting) and then scroll backwards through the output, looking forthe detailed error message.

For example, in the debug output below, the end of the output shows themessage “Thread-31, SEND SSL

v3.0 ALERT: fatal, description = certificate_unknown”. Scrolling backwards through thelog, themessage “out of date cert” appears before the last certificate was processed; the certificate’sinformation shows that the certificate had expired in 2002.

The following example includes the beginning of the debug output and the last section with the error:

keyStore is :keyStore type is : jksinit keystoreinit keymanager of type SunX509trustStore is: /usr/java1.3/jre/lib/security/cacertstrustStore type is : jksinit truststoreadding as trusted cert: [

………………

out of date cert: [[Version: V3Subject: O=HC, CN=204.165.200.98Signature Algorithm: SHA1withRSA, OID = 1.2.840.113549.1.1.5

Key: com.sun.net.ssl.internal.ssl.JSA_RSAPublicKey@187197Validity: [From: Sun Jun 18 07:16:00 EDT 2000,

To: Tue Jun 18 07:16:00 EDT 2002]Issuer: O=HC, OU=Organizational CASerialNumber: [ 021411e9 6f9a05e1 28e9293c c80ae5b5 1166338c 1cbc0201 0c]

Certificate Extensions: 3[1]: ObjectId: 2.16.840.1.113719.1.9.4.1 Criticality=falseExtension unknown: DER encoded OCTET string =0000: 04 82 01 BD 30 82 01 B9 04 02 01 00 01 01 FF 13 ....0...........0010: 1D 4E 6F 76 65 6C 6C 20 53 65 63 75 72 69 74 79 .Novell Security0020: 20 41 74 74 72 69 62 75 74 65 28 74 6D 29 16 43 Attribute(tm).C0030: 68 74 74 70 3A 2F 2F 64 65 76 65 6C 6F 70 65 72 http://developer0040: 2E 6E 6F 76 65 6C 6C 2E 63 6F 6D 2F 72 65 70 6F .novell.com/repo0050: 73 69 74 6F 72 79 2F 61 74 74 72 69 62 75 74 65 sitory/attribute0060: 73 2F 63 65 72 74 61 74 74 72 73 5F 76 31 30 2E s/certattrs_v10.0070: 68 74 6D 30 82 01 4A A0 1A 01 01 00 30 08 30 06 htm0..J.....0.0.0080: 02 01 01 02 01 46 30 08 30 06 02 01 01 02 01 0A .....F0.0.......0090: 02 01 69 A1 1A 01 01 00 30 08 30 06 02 01 01 02 ..i.....0.0.....00A0: 01 46 30 08 30 06 02 01 01 02 01 0A 02 01 69 A2 .F0.0.........i.00B0: 06 02 01 17 01 01 FF A3 82 01 06 A0 5A 02 01 02 ............Z...00C0: 02 02 00 FF 02 01 00 03 0D 00 80 00 00 00 00 00 ................00D0: 00 00 00 00 00 00 03 09 00 80 00 00 00 00 00 00 ................00E0: 00 30 18 30 10 02 01 00 02 08 7F FF FF FF FF FF .0.0............00F0: FF FF 01 01 00 02 04 06 F0 DF 48 30 18 30 10 02 ..........H0.0..0100: 01 00 02 08 7F FF FF FF FF FF FF FF 01 01 00 02 ................0110: 04 06 F0 DF 48 30 58 A1 58 02 01 02 02 02 00 FF ....H0X.X.......0120: 02 01 00 03 0D 00 40 00 00 00 00 00 00 00 00 00 [email protected]: 00 00 03 09 00 40 00 00 00 00 00 00 00 30 18 30 [email protected]


9.1 S

P6 BETA D

RAFT

Authentication > About Web Server Delegation Authentication

0140: 10 02 01 00 02 08 7F FF FF FF FF FF FF FF 01 01 ................0150: 00 02 04 11 E9 6F 9A 30 18 30 10 02 01 00 02 08 .....o.0.0......0160: 7F FF FF FF FF FF FF FF 01 01 00 02 04 11 E9 6F ...............o0170: 9A A2 4E 30 4C 02 01 02 02 01 00 02 02 00 FF 03 ..N0L...........0180: 0D 00 80 00 00 00 00 00 00 00 00 00 00 00 03 09 ................0190: 00 80 00 00 00 00 00 00 00 30 12 30 10 02 01 00 .........0.0....01A0: 02 08 7F FF FF FF FF FF FF FF 01 01 00 30 12 30 .............0.001B0: 10 02 01 00 02 08 7F FF FF FF FF FF FF FF 01 01 ................01C0: 00 .

[2]: ObjectId: 2.5.29.35 Criticality=falseAuthorityKeyIdentifier [KeyIdentifier [0000: 01 .]

]

[3]: ObjectId: 2.5.29.15 Criticality=falseKeyUsage [DigitalSignatureKey_Encipherment

]

]Algorithm: [SHA1withRSA]Signature:

0000: 50 75 22 E0 14 FE E7 50 FE 44 3B 36 D2 C8 EC 10 Pu"....P.D;6....0010: 49 8D 48 1D 6F E6 91 1A 05 1E 8E FD 69 D3 4D 70 I.H.o.......i.Mp0020: C3 3C FE 14 D0 D4 99 DE CA BF 23 57 80 A0 04 F2 .<........#W....0030: 45 33 BD B0 53 2D 72 A1 43 DD 7C 80 DD 6B 3E EC E3..S-r.C....k>.0040: 94 73 F9 83 21 2C 80 17 B1 CE 6E 19 FD 14 FF A8 .s..!,....n.....0050: C0 CB 51 C7 1A C1 C0 E4 71 2F 46 9D 50 91 52 E8 ..Q.....q/F.P.R.0060: 5B CA 24 84 FF 7F 3E 84 32 09 AA 43 66 E8 CD AB [.$...>.2..Cf...0070: 65 EC 5C 89 88 43 3C 15 07 3C 9D 52 AA CF 31 A1 e.\..C<..<.R..1.0080: C9 B6 3A 7A CC 35 1B 66 CB 3C 80 00 32 15 76 2F ..:z.5.f.<..2.v/0090: 86 82 26 31 2F C3 EC 58 CE DD E8 E6 A4 58 6E F0 ..&1/..X.....Xn.00A0: 70 14 36 DF CB 29 E0 E7 D4 1A 33 62 4E B7 62 3C p.6..)....3bN.b<00B0: 77 54 9E AA BE 57 0E 7C F2 E1 92 D5 B0 AF E9 BB wT...W..........00C0: 20 CA A7 AA 4F D4 37 02 DE B2 16 9D FC 7E 90 63 ...O.7........c00D0: 10 22 49 20 76 97 83 8A 83 0E BB A6 7B B0 E4 DE ."I v...........00E0: FB 62 51 FD 92 EB 9F C7 B6 91 F2 94 5C 93 29 11 .bQ.........\.).00F0: B9 A2 AE 28 46 00 BE 14 EC 1C F8 6C 63 A3 10 BA ...(F......lc...

]Thread-31, SEND SSL v3.0 ALERT: fatal, description = certificate_unknownThread-31, WRITE: SSL v3.0 Alert, length = 2

About Web Server Delegation AuthenticationWeb servers support a range of technologies for identifying and authenticating users. By default, the applicationserver (Tomcat) handles authentication. DuringWeb Server Delegation authentication, the application serverdelegates some aspects of authentication to theWeb server (Apache® or IIS).

ManagementWhen usingWeb server delegationmuch of the work related to the authentication is handled on theWebserver. The process forWeb server authentication is:

1. Obtain the credentials of the user.2. Verify the user’s credentials.3. Set a header in the request that is populated with the value for the CGI variable REMOTE_USER.


9.1 S

P6 BETA D

RAFT

Authentication > Web Server Delegation with Windows 2003

4. If a custommodule has been created, it will look for the header name that was set in Step 3. If itfinds this header, the value will be used as the external user ID.

Steps 1 through Step 3must be implemented by aWeb server module/filter. For example, Blackboard providesan Active Directory filter for IIS. Clients using UNIX can set up Kerberos with Apache. The administrator mustensure that the authentication filter has been installed on theWeb server. If usingWindows®, see About ActiveDirectory Authentication.

Step 4 takes place within the application server and requires that the authtype.webserver.impl isspecified in the authentication.properties file.

Note: Kerberos authenticationmay be incompatible with direct access toWebDAV. Institutions using thistype of authenticationmay be able to take advantage of WebDAV by first authenticating with Blackboard Learn,and then launching theWeb Folder from within the user interface.

ImplementationThe following are steps for implementingWeb server delegation:

1. Install the appropriate filter (for example, Kerberos on Apache).2. Update the authentication.properties file if needed.3. Restart the application server and theWeb server.

Web Server Delegation with Windows 2003It is necessary to complete some additional steps to useWeb Server Delegation withWindows 2003. Note thatActive Directory authentication is a form of Web Server Delegation.

How to Configure Web Server Delegation with Windows 20031. Edit the authentication.properties file. To learnmore, see Active Directory Property

Configuration.2. Edit the bb-config.properties file to change bbconfig.auth.type to

bbconfig.auth.type=webserver.3. Deploy the configuration updates by running cd BB_DEPLOY_DIR\tools\admin

PushConfigUpdates.bat.

Running PushConfigUpdates will overwrite any customizations to the configuration. To learnmore, see PushConfigUpdates.

4. Run websitereinstall.bat, which will delete and recreate the Blackboard website. Allcustom changes to IIS will be removed, including configurations to support SSL Choice.

5. Open IIS 6.0.6. Right click on the Blackboard website and click Properties.7. In the IIS Management Console for Blackboard Learn, select the authenticationmethod or

methods. The options areBasic, Digest, and Integrated Windows authentication. One or moreoptions may be selected.

8. Click the ISAPI Filters tab. Verify that theWindows .dll has been added. Also, verify the orderof the filters. They should be in the following order: Sessiontracker, Windows, Jakarta. If they arenot in order, move them into the correct order.

9. Click Apply.10. Click OK.


9.1 S

P6 BETA D

RAFT

Authentication > About Custom Authentication

About Custom AuthenticationCustom authentication enables developers to create a customized authenticationmodule that may be pluggedinto the authentication framework of Blackboard Learn. Blackboard Learn ships to clients with severalauthentication techniques, each with its own associatedmodule.

Developing customized authentication allows clients to do either of the following:

l Replace the pre-built modules with amodule provided by the client or by a third party.l Specify a different authentication technique with its own properties. Any module that conforms to the

Blackboard End-User Authentication API may be substituted.

The Blackboard Challenge-Response authentication type is installed by default, and will be referred to as “thedefault authentication type” throughout this section. Module refers to a Java class that implements the interfaceblackboard.platform.security.authentication.HttpAuthModule. To learnmore about thisinterface, see About Authentication through the API.

Note: For questions about creating highly customized authentication implementations, please contactBlackboard Technical Solutions.

AudienceDevelopers who wish to create a customized authenticationmodule should have the following:

l A good understanding of general security principles, especially regarding authentication andWebbased security.

l Experience with Java servlet programming.

Data ModelThere is no dedicated datamodel for authentication. However, the default authentication process relies on thepassword and user name attributes of the user entity. For details about the datamodel, see the BlackboardBuilding Blocks Extension Developer’s Guide.

Setting Up and Deploying Custom ImplementationsThis section explains how developers may use the implementations provided by Blackboard Learn to createcustom authenticationmodules for their Institution. It also reviews how to extend Blackboard Learn defaultimplementation for a custom authenticationmodule and how to create custom authenticationmodules forLDAP andWeb server delegation.

Extending Blackboard-provided ImplementationsRather than creating a custom implementation of the HttpAuthModule interface from scratch, clients maycreate a Java class that inherits from one of the HttpAuthModule implementations included with BlackboardLearn. Re-using existing application components allows for custom authentication functionality with aminimumof development effort.


9.1 S

P6 BETA D

RAFT

http://library.blackboard.com/d?05c6037c-b06d-4507-929e-16601a094cbb






Authentication > Setting Up and Deploying Custom Implementations

Extending the Blackboard Default ImplementationThe default implementationmay be re-used to simplify implementations that only require custom processing ofthe user credentials. This has the added benefit of being able to re-use the challenge/response features of thedefault implementation without duplicating code.

The simplest way to extend the default implementation is to extend the classBaseAuthenticationModule, over-riding only the doAuthenticate()method.

The doAuthenticate()method returns a string representing the username for the user who has beenauthenticated. Subclasses of BaseAuthenticationModulemay either completely over-ride thedoAuthenticate()method, or re-use the result. The following is an outline of an implementation that re-uses the result:

import blackboard.platform.security.authentication.*;

public class CustomAuthModule extends BaseAuthenticationModule

throws BbSecurityException, BbAuthenticationFailedException,BbCredentialsNotFoundException

{

public String doAuthenticate(HttpServletRequest request,


{

// Get the default authentication technique’s result

String username = super.doAuthenticate( request, response );

/* OUTLINE OF POSSIBLE CUSTOM AUTH CODE */

// Check some data source external to Blackboard Learn

// Do some extra processing related to custom authentication check

// Return the username if no exceptions have been thrown

return username;

}

}

Alternatively, any or all of themethods in the HttpAuthModule interfacemay be overridden in customauthenticationmodules.

Creating a Custom LDAP ImplementationThe Blackboard LDAPAuthModule is a very straightforward implementation of LDAP authentication. CustomLDAP implementations that wish to extend the functionality of the Blackboard LDAPAuthModule by binding toa given LDAP schema and performing queries specific to that schema can do so by subclassing from theBlackboard class and overriding its authenticate()method. The LDAP modulemay be extended to addadditional behavior (such as additional processing after calling super.authenticate()). However,changing the behavior of the LDAP module cannot be overridden. If the Blackboard-supplied LDAP module isnot sufficient, a completely new module (extending BaseAuthenticationModule) could be developed toaccess the LDAP directory in a specialized way

For a detailed discussion of the property settings for LDAP authentication, see Setting Up LDAP AuthenticationProperties.


9.1 S

P6 BETA D

RAFT

Authentication > Setting Up and Deploying Custom Implementations

Creating a Custom Web Server Delegation ImplementationFor custom authentication implementations that rely onWeb server modules or filters,ExternalAuthModule has been provided as the simplest possible implementation. TheExernalAuthModulemethod parses the request and extracts the CGI variable REMOTE_USER as the username to authenticate against. The customWeb server delegation implementation would only need to install amodule or filter (for example, Kerberos on Apache) on theWeb server and configure it to populate the requestwith the CGI variable REMOTE_USER.

Deploying Custom ImplementationsOnce the .JAR file containing the .class file for the custom authentication class is built, place the .JAR file inthe tomcat auto load directory.

The custom .JAR files are stored in the common classloader of Tomcat. Follow the steps below:

1. Open the directory config/tomcat/classpath and create a new text file namedyourinstitution-common.classpath.bb.

2. Open this text file and enter the full name of the .JAR files that should be included in the classpath.3. Run PushConfigUpdates to copy the file to the correct location. To learnmore, see

PushConfigUpdates.

Note: A copy of the jar file should be in /systemlib. Additionally, edit /system/build/bin/launch-

tool.bat (or .sh on Unix) and append the .jar files to the BB_CP variable. Otherwise, command line tools thatbootstrap the core services (for example, LogRotation or PurgeAccumulator) will not work.

Updating the Collaboration ServerAdministrators who use custom authenticationmay experience issues with the Collaboration server. Thecollaboration server breaks because of the AccessManager in service-config-collab-server.properties. This issuemay be resolved by adding the custom authenticationmodule class to thecollaboration server's classpath. Follow the steps below:

How to Update the Collaboration Server in Windows1. Add the classpath to the location of the authenticationmodule classes (either a path to a directory,

or a path to a jar file) to the install-nt-services.bat.bb. Administrators may use thewildcard syntax for the Blackboard install directory.


Note: When updates to the system are installed, the .bb file may be overwritten. Save a copy of the .bb filebefore an update and use this copy to replace the .bb template.

How to Update the Collaboration Server in UNIX1. Add the classpath to the location of the authenticationmodule classes (either a path to a directory,

or a path to a jar file) to the collabserverctl.sh.bb. Administrators may use the wildcardsyntax for the Blackboard install directory.


Note: When updates to the system are installed, the .bb file may be overwritten. Save a copy of the .bb filebefore an update and use this copy to replace the .bb template.


9.1 S

P6 BETA D

RAFT

Authentication > Setting Up Customized Authentication Page Flow

Updating the launch-tool ScriptAdministrators should add the custom authentication jar file to the classpath of the launch-tool andlaunch-app scripts to prevent issues with the PurgeAccumulator tool and other administrative tools.

How to Update the launch-tool Script in WindowsAdd the classpath to the location of the authenticationmodule classes (either a path to a directory, or a path to ajar file) to the launch-tool.bat. This file is located in blackboard\system\build\bin.

Note: Save a copy of the files before attempting to add the classpath.

How to Update the launch-tool Script in UNIXAdd the classpath to the location of the authenticationmodule classes (either a path to a directory, or a path to ajar file) to the launch-tool.sh. This file is located in blackboard/system/build/bin.

Note: Save a copy of the files before attempting to add the classpath.

Using WebDAV with a Custom ImplementationForWebDAV access to the Content Collection to function correctly when a Custom AuthenticationModule isdeployed, themodulemust implement IUserPathAuthModule for LDAP implementations orExternalAuthModule for all other custom implementations. For information about implementingIUserPathAuthModule, see Planning Authentication Implementation.

Troubleshooting Custom ImplementationsThis section explains how to troubleshoot problems that may occur when installing a custom authenticationmodule.

l Examine the tomcat logs in \blackboard\logs\tomcat and \blackboard\logs\bb-services-log.txt files for Java errors that may occur

l Ensure that the class name is correctl Ensure that all of the properties are correctly defined in the authentication.properties filel Ensure that the authenticationmodule (and all of its dependencies) are in the .JAR file and are in the

proper locationl If subclassing BaseAuthenticationModule or other implementations, make sure that there are

no namespace conflicts that may affect processing

Setting Up Customized Authentication Page FlowThis section discusses how to customize the routing between pages in Blackboard Learn. An Institutionmaycustomize routing by uploading a custom login page to Blackboard Learn server (via theCustomize LoginPage link on the System Control Panel), or by implementing the requestAuthenticate()method on theHttpAuthModule interface.

TheCustomize Login Page function on the System Control Panel allows the Administrator to download atemplate for the login page and then upload amodified template to the server. This allows the Administrator toadd extra script functionality to the login page hosted by Blackboard Learn.


9.1 S

P6 BETA D

RAFT

Authentication > About Authentication through the API

Note: Institutions interested in customizing their Blackboard Learn login pagemust not remove the JSP tagson the page.

Implementing requestAuthenticate()If the user wishes to redirect to a login form on a page hosted by another application, instead of using theCustomize Login Page function, the user should implement the HttpAuthModule interfacemethodrequestAuthenticate() to do a redirect.

For authentication to function properly, any login form on a page hosted by another applicationmust submit theform to the login broker at the Institution’s URL (for example, a login page hosted at“http://another.institution.com”must submit its login form to the URL“http://your.institution.edu/webapps/login”).

Redirecting to the Original Target URLIf a user has clicked a bookmarked URL that leads into the Blackboard Learn, but they are not currentlyauthenticated, the application will route the user to the login broker URI with the originally requested URLpreserved. The login broker expects that the rest of the application will preserve the originally-requested URL,in URL-encoded form, as either a hidden form variable or a query string parameter named new_loc. Anycustom Login page uploaded to the Blackboard Learn server, or any third-party script page thatrequestAuthenticate() redirects to, must keep this contract as well. If not, the Blackboard Learn willroute to its default entry page.

About Authentication through the APIThis section explains the different methods that require implementation for the authentication process. TheAuthentication API is defined by the Java interfaceblackboard.platform.security.authentication.HttpAuthModule. All custom authenticationmodules must implement this interface.

To learnmore about the arguments and returns for eachmethod, see the API Specifications.

Authentication Processing MethodsThe following authentication processingmethods are implemented in the authenticationmodule. See thesample authenticationmodule below for an example of the usage of thesemethods.

init()init() is called by the authentication framework when it creates an instance of HttpAuthManager, whichin turn creates an instance of the appropriate authenticationmodule and allows the implementation class toperform any required initialization. The sole argument passed in is the ConfigurationService objectcreated during system startup. This method is intended to cache properties relevant to custom authenticationthat are defined at system startup. Installation specific properties can be obtained from theConfigurationService and is different from the properties passed in setConfig(). See the followingmethod example.

An authenticationmodule that needs to insert a completely new set of entries in theauthentication.propertiesmust implement an init()method that calls the configure()methodon the class HttpAuthConfig. To learnmore, see Configuration File ProcessingMethods.

/*


9.1 S

P6 BETA D

RAFT


* Module initialization. This method gets called when Tomcat starts up.

*/

public void init(ConfigurationService arg0) throws

IllegalStateException {

//Although this is not necessary for subclasses of

//BaseAuthenticationModule, it is a good practice to do this

//unless there is a reason not to.

super.init(arg0);

try {

// Set up logging

_logger = BbServiceManager.getLogService();

} catch (RuntimeBbServiceException e) {

e.printStackTrace();

}

if (_logger == null) {

// This println statement will output to the

//stdout-stderr.log file.

System.out.println("logger is null");

} else {

_logger.logWarning("Custom Auth Module: init()");

}

}

requestAuthenticate()requestAuthenticate() is called if the user is not logged into the Blackboard Learn. The implementationmay prompt the user for their credentials. This methodmay be used for the following:

l to generate a HTTP-302 status in the response, or Javascript, to redirect to a login URLl to generate a login form programmatically via the servlet APIl to generate an HTTP-401 responsel to forward the user to the appropriate point in the customized Blackboard Learn (for example, by using

a javax.servlet.RequestDispatcher.forward())

/*

* Gets called when the user needs authenticating.

*/

public void requestAuthenticate(


HttpServletResponse response) throws BbSecurityException {

//Do the superclass implementation, redirect to the Default Login

//Page

_logger.logWarning("Custom Auth Module: requestAuthenticate()");

super.requestAuthenticate(request, response);

}


9.1 S

P6 BETA D

RAFT


doAuthenticate()doAuthenticate() is called for the implementation to:

l parse the requestl extract any credentialsl perform the authentication work

/*

* Does the work of authenticating the user.

*/

public String doAuthenticate(



throws BbSecurityException,

BbAuthenticationFailedException,

BbCredentialsNotFoundException {

//Do custom processing here, just make sure

//the user name is returned or the appropriate exception

//is thrown.

_logger.logWarning("Custom Auth Module: doAuthenticate()");

return super.doAuthenticate(request, response);

}

doLogout()doLogout() is called when the user explicitly logs out. The implementationmay perform any tasks required ofits authentication authority and remove any session variables. Custom authenticationmodules that subclassBaseAuthenticationModulemay use its implementation to clean up Blackboard Learn specific sessioninformation.

/*

* Gets called when the user explicitly logs out.

*/

public void doLogout(




_logger.logWarning("Custom Auth Module logging out");

//If subclassing BaseAuthenticationModule, the superclass

//implementation can be called. It basically performs the

//work of invalidating a user’s session.

SessionStub sessionStub = new SessionStub( request );

sessionStub.disassociateCurrentSessionAndUser();

}

Note: This methodmay not be called since users may close their browser and not explicitly log out.


9.1 S

P6 BETA D

RAFT


isAuthenticated()isAuthenticated() has been deprecated and is only included tomaintain backward compatibility. IfBaseAuthenticationModule is being extended, no implementation is necessary.

Note: Implementing this method will not over-ride the login broker’s internal checks that determine whether thecurrent Blackboard Learn session is authenticated.

Of the above interfacemethods, the key methods for cooperating with the login broker aredoAuthenticate(), requestAuthenticate() and doLogout().

Configuration File Processing MethodsThe authentication framework expects to find an authentication.properties file in the/blackboard/config directory of Blackboard Learn. The classblackboard.platform.security.authentication.HttpAuthConfig loads theauthentication.properties settings intomemory andmanages the process of configuring anHttpAuthModule object with the appropriate settings.

If an Institution wishes to create a custom authenticationmodule that requires a completely new set of entriesin the authentication properties file, then all three HttpAuthModulemethods described below must beimplemented by the custom authenticationmodule.

getAuthType()getAuthType() returns a String identifier for the authentication technique. The four authentication techniquessupported by the Blackboard Learn (Blackboard default authentication, LDAP, andWeb server delegation) arerepresented as “rdbms”, “ldap”, and “webserver”. The authentication framework loads this String identifier fromthe bb-config.properties setting for bbconfig.auth.type. The authentication framework thenrequests that the HttpAuthConfig class, which has loaded all settings found in theauthentication.properties setting, creates an HttpAuthConfig instance which stores allauthentication.properties settings with the given auth.type identifier. For example, ifbbconfig.auth.type is set to ldap, then all property settings that match auth.type.ldap are loaded intoa new HttpAuthConfig instance. This method should be implemented for every authenticationmoduleclass. For example, with the Sample Custom AuthenticationModule, the following entry needs to be changedin the bb-config.properties file:

auth.type.custom.impl=blackboard.authentication.test.CustomAuthModule

getPropKeys()getPropKeys() returns a String array of the keys to an authenticationmodule's configuration properties. Forexample, the BaseAuthenticationModule has the keys “impl” and “use_challenge”. This method shouldbe implemented for every authenticationmodule class. The array must contain all of the property keys for thecustom implementation. At aminimum, themethod should return the “impl” property which specifies the fullyqualified class name of the HttpAuthModule implementation. In order to obtain the value of the properties,the authenticationmodule can use the HttpAuthConfig.getProperty()method with the property name.Only the property name need be specified, not the entire entry in the authentication.properties file. Forexample, with the Sample Custom AuthModule, the following entries need to be added to theauthentication.properties file:

auth.type.custom.impl=blackboard.authentication.test.CustomAuthModule

auth.type.custom.prop1=test

To get the property of prop1, the followingmethod can be used:


9.1 S

P6 BETA D

RAFT

Authentication > Using Servlet Authentication

// _config has already been defined as a member variable of type HttpAuthConfig

String prop1 = _config.getProperty(“prop1”);

setConfig(HttpAuthConfig config)setConfig(HttpAuthConfig config) implies a contract between HttpAuthModule andHttpAuthConfig, such that HttpAuthConfig is expected to supply the correct object for a given propertykey. Subclasses of BaseAuthenticationModule do not need to implement this method, and can use the _configmember variable to obtain configuration properties.

Using Servlet AuthenticationThe servlet that initializes Blackboard Learn calls HttpAuthManager.init(), which does the following:

l Loads the authentication configuration settingsl Creates and initializes an instance of an HttpAuthModule implementation classl Installs the instance into the HttpAuthManager class

LoginAuthentication processing in the Blackboard Learn is centralized in a login-broker servlet, installed at/webapps/login. The login-broker servlet processes all login requests for the Blackboard Learn. Loginrequest universal resource identifiers (URIs) take the form of /webapps/login.

Every JSP page in Blackboard Learn that requires an authenticated user session does one of the following:

l Redirects to the login brokerl Displays a link to the login broker if the current user is not logged in or is not logged in as a user with

sufficient authorization for the page

The following image demonstrates how the login-broker servlet processes login requests.

The login-broker servlet invokes themethod validateSession() on a HttpAuthManager instance. TheHttpAuthManagermethod validateSession() calls the doAuthenticatemethod on themoduleinstalled on the HttpAuthManager class. The servlet uses the boolean result of this method to determine


9.1 S

P6 BETA D

RAFT

Authentication > Using Servlet Authentication

whether to invoke themethod sendNewLocRedirect() on the HttpAuthUtil class, or to trigger therequestAuthenticate()method on HttpAuthManager object.

The sendNewLocRedirect()method on the HttpAuthUtil class retrieves the new_loc parameter inthe request, translates it to a URL and forwards the request to that URL.

The requestAuthenticate()method on the HttpAuthManager calls therequestAuthenticate()method on themodule that was installed during system startup. Themodule’srequestAuthenticate()method is called so the implementationmay prompt the user for credentials.These credentials must then be submitted to the login broker via HTTP.

LogoutThe login-broker servlet also processes all logout requests for the Blackboard Learn. Logout request URIs takethe form of /webapps/login?action=logout.

The servlet invokes themethod invalidateSession() on a HttpAuthManager instance. After thesession is invalidated, the servlet forwards the request to the index page Blackboard Learn.

When a user’s session has timed out, and the user tries to access a page in the Blackboard Learn that requiresan authenticated user session, the system redirects the user to the login broker.


9.1 S

P6 BETA D

RAFT

SSL > About SSL and SSL Choice

SSL

About SSL and SSL ChoiceSecure Sockets Layer (SSL) is a protocol for protecting Internet communications. SSL ensures that acommunication is not read or changed by another entity. Blackboard Learn uses SSL to secure all or somecommunications between theWeb server and the client machine. This feature that allows Administrators toselect which areas of Blackboard Learn are secured using SSL is called SSLChoice.

Note: SSLmay also be used to secure the connection between Blackboard Learn and a separate server forauthentication (such as an Active Directory server). If SSL will be used both for connecting to an authenticationserver and for client sessions, SSL for the authentication server must be configured first. To learnmore aboutconfiguring SSL for securing with an integrated authentication server, see Using Blackboard LearnAuthentication.

Note: SSL Off-loading is not supported.

How Does SSL Work?SSLworks through public key encryption. Transmissions are decrypted and encrypted using certificates. Thesteps below outline the process for establishing a connection over SSL:

1. Client contacts the server with a list of encryptionmethods.2. The Server returns its certificate and a public key. These initial communications are scrambled with

random data.3. Client validates the certificate.4. Client creates a secret string using an encryptionmethod recognized by both the client and the

server. The string is combined with the server's public key and sent back to the server.5. Both the client and server create session keys based on the secret string.6. The client sends amessage to the server that it will now use the session key to encrypt and

decrypt communications.7. The server responds that it will also use the session key.8. After each side confirms, the session keys are used to encrypt and decrypt communications during

the session.

How to Obtain a CertificateThe simplest way to obtain a certificate for use with aWeb site is through a vendor known as a CertifyingAuthority (CA). The process, shown in the steps below, is relatively simple.

1. Generate a certificate request.2. Send the request to a CA.3. The CA creates and registers a certificate.4. Make this certificate available to theWeb Server (IIS or Apache).

Certificates created in this way are usually registered and good for one year. After one year the certificate willno longer work and a new certificate must be obtained.

Note: If using a self-signed certificate, the certificate must be added to the list of allowed certificates on theclient machine. If this is not done, themulti-upload feature will fail, as will a few other features that use SSL.


9.1 S

P6 BETA D

RAFT

SSL > Setting Up SSL for IIS

How Does SSL Appear to Users?SSLworks with the Hypertext Transfer Protocol (HTTP) to secure connections between Blackboard LearnWeb server and the client machines. It is fairly easy to see when aWeb page is using SSL to securetransmissions because an “s” is appended to the http at the beginning of the address.

Without SSL: http://blackboard.yourinstitution.com

With SSL: https://blackboard.yourinstitution.com

It is important to understand that if SSL is used to secure theWeb page in this example then the first URL(without SSL) is invalid and will return a 404 error.

SSL ChoiceThe SSLChoice feature is available in the user interface from the System Control Panel. It allows an institutionto decide if all, none, or some of Blackboard Learn is secured with SSL. If SSL is to be used, it is most effectivewhen applied to the entireWeb site and not just selected areas.

Note: SSLmust be configured on theWeb Server before using the SSLChoice feature. If SSL Choice isturned on before theWeb server is configured then any areas set to use SSLwill be unavailable to users!

Setting Up SSL for IISTo use SSL to secure Blackboard Learn the IIS Web server must first be set to use SSL. Configuring SSLshould only be done by an experiencedMicrosoft administrator.

Once SSL is configured, the SSLChoice feature (accessible from the Administrator Control Panel) will functioncorrectly. Trying to use the SSLChoice feature before configuring SSL for Apache can result in serious systemerrors.

How to Configure SSL for IIS1. Open the Internet Services Manager.2. Right-click on the blackboard_bblearnWeb site and select Properties from themenu.3. Click theDirectory Security tab.4. Click Server Certificate in the Secure communications frame at the bottom of the tab.5. TheWeb Server CertificateWizard will appear. The Status of your Web server should report that

there is not a certificate installed and there are no pending requests. If anything else appears, theremay be a certificate installed or a pending request already. Click Next to advance.

6. Select Create a new certificate and click Next to advance.7. Select Prepare the request now, but send it later and click Next to advance.8. Enter a name for the certificate (the name of theWeb site in IIS is the default) and select a bit

length from the drop-down list. Blackboard recommends a bit length of 1024. Click Next toadvance.

9. Enter the name of yourOrganization and yourOrganizational unit in the fields. This informationis important to ensure that your certificate is unique and easily identified. Click Next to advance.

10. Enter theCommon name of theWeb site. The host plus the domain nameworks best (example:blackboard_server.yourinstitution.edu). Click Next to advance.

11. Enter the appropriate geographical information for your institution. Click Next to advance.


9.1 S

P6 BETA D

RAFT

SSL > Setting Up SSL for Apache

12. Enter a file name for the certificate request or click Next to select the default and advance.13. Click Finish to create the certificate request.14. Send the certificate request to a Certifying Authority. There are several commercial vendors or you

can sign your own if you have the capability. The output from the Certifying Authority will be a filewith the extension .cer.

15. Once you have obtained a .cer file, return to theWeb Server Certificate Server as described inSteps 1-4.

16. Select Process the Pending Request and click Next to advance.17. Enter the location of the .cer file and click Next to advance.18. Click Next to advance through the summary steps (be sure to review the summaries tomake sure

you are installing the correct certificate!).19. Return to theProperties box for the blackboard_bblearnWeb site as described in Steps 1

and 2.20. If theWeb Site tab is not active, select it.21. Enter 443 for theSSL Port in theWeb Site Identification frame at the top of the tab.22. Restart the server to complete the process.

Setting Up SSL for ApacheTo use SSL to secure Blackboard Learn the ApacheWeb server must first be set to use SSL.

Note: Successful completion of this process requires that Solaris users are running Solaris 10, Solaris 9, orSolaris 8 with patch 112438-02.

Configuring SSL should only be done by an experienced administrator.

Once SSL is configured, the SSLChoice feature (accessible from the Administrator Control Panel) will functioncorrectly. Trying to use the SSLChoice feature before configuring SSL for Apache can result in serious systemerrors.

How to Configure SSL for Apache1. Login to theWeb/application server as root.2. Set the PATH to include theOpenSSL provided by Blackboard with the following commands:

PATH=/blackboard_home/apps/openssl/bin:$PATH

export PATH

3. Test that OpenSSL is in the PATH by executing openssl. If OpenSSL is set in the PATHcorrectly, an OpenSSL> prompt will appear. Enter ‘q’ to exit the prompt. If another instance ofopenssl is installed on the operating systemmake sure that the version supplied by Blackboard isthe version that appears in the PATH.

4. Create a directory to store certificates. Then change directories. For example:mkdir /blackboard_home/apps/httpd/conf/certs/

cd /blackboard_home/apps/httpd/conf/certs/

5. Create a RSA private key:openssl genrsa –out server.key 1024

where server is a variable for the file name. Typically the server name is used.


9.1 S

P6 BETA D

RAFT

SSL > Setting Up SSL Choice

6. Backup this file andmake sure that only root has read permissions on it. Make sure that thepassword is secure and can be recalled when necessary. (need to recall to start the server).

7. Create a Certificate Signing Request (CSR) for the server RSA private key with the followingcommand:openssl req –new –days 365 –key server.key –out server.csr

The –days option sets the expiration of the certification. Most Certifying Authorities will only sign acertificate for 1 year. At that time the certificate must be resigned.

8. View the details of the CSR with the following command:openssl req –noout –text –in server.csr

When submitting the request, it may be necessary to view the file and copy text from it forsubmission to the Certifying Authority (CA).

9. Send the CSR to a Certifying Authority for signing. There are several commercial options availableor you can sign your own if you have the capability. The output of either process is a server.crtfile.

10. Edit the /blackboard_home/apps/httpd/conf/httpd.conf file to include the followingdirective:Include conf/ssl.conf

11. Edit the /blackboard_home/config/bb-config.properties file by modifying thefollowing attributes, as shown below.bbconfig.unix.ssl.certificatefile=/path/server.crt

bbconfig.unix.ssl.certificatekeyfile=/path/server.key

12. Restart the server.13. The SSLChoice feature can now be used to select which areas of Blackboard Learn use SSL. To

learnmore about using SSLChoice, see Setting Up SSLChoice.

Setting Up SSL ChoiceAfter IIS or Apache is configured to support SSL, then the communication between users and Blackboard Learncan be configured using the SSLChoice feature. SSL Choice allows Administrators to determine if none, all, orsome of Blackboard Learn is secured with SSL.

Note: If the SSLChoice is set to use SSL before SSL is configured in IIS or Apache Blackboard Learn will notbe accessible! To ensure that users can always login, configure IIS or Apache for SSL prior to changing thesecurity options on the SSLChoice page.

If planning on using SSL, Blackboard recommends enforcing SSL on the entire system. This ensures that allproprietary data is secured. If the choice option is chosen, it is important to update SSL settings whenever anew tool is enabled or a System Extension added.

How to Set Up SSL Choice1. From the Security and Integration section of the System Control Panel, click SSL Choice.2. Set the properties using the following table, and then click Submit.

Field Description

System-wide


9.1 S

P6 BETA D

RAFT

SSL > Setting Up LDAP Authentication with SSL

Field Description

Disable SSL System-wide

Select this option and SSL will not be used to secure any of thecommunication between users and Blackboard Learn.

Enable SSL System-wide

Select this option and SSL will be used to secure all of the communicationbetween users and Blackboard Learn.

Enable SSL for thefollowing areas

Select this option to determine which areas of Blackboard Learn will besecured through SSL. Select the different areas from the check boxes on thispage.

Specific Areas

Select the check box for each area that should be secured using SSL.

Tools

Select the check box for each tool, tab, or Course content area that should be secured using SSL.

Building Block Tools

Select the check box for each Building Block that should be secured using SSL.

Proxy Tools

Select the check box for each Proxy Tool that should be secured using SSL.

Web Services

Select the check box for each Web Service that should be secured using SSL.

Setting Up LDAP Authentication with SSLThis section explains how to configure the authentication.properties file settings that enableBlackboard Learn, using LDAP authentication, to communicate with an LDAP Server over SSL. No extraentries need to be added to the authentication.properties file. The Administrator simply needs to setthe appropriate properties correctly (see table below).

Note: The SSLChoice option in the System Control Panel is used to secure communication betweenBlackboard Learn and the client machine. To learnmore, Setting Up SSLChoice.


auth.type.ldap.server_url.x

When the LDAP server is setup to communicate over SSL, this property should be:ldap://directory.university.edu

Administrators may need to append the port number depending upon theconfiguration.

auth.type.ldap.server_ssl.x

Must be set to "true" or "false". If set to "true" the module will attempt to connect to theLDAP directory using SSL. The LDAP server must be set up to handle SSLconnections.

Run PushConfigUpdates after editing the properties file. To learnmore, see PushConfigUpdates. Finally,copy the JSSE, JNET, and JCERT files from apps/tomcat/shared/lib and paste these files into the$JAVA_HOME/jre/lib/ext directory.


9.1 S

P6 BETA D

RAFT

SSL > How to Configure LDAP Authentication with SSL for the JAVA Runtime Environment (JRE)

How to Configure LDAP Authentication with SSL for the JAVARuntime Environment (JRE)

1. Copy the following three files to the JAVA_HOME\jre\lib\ext directory:\blackboard\systemlib\jcert-1.0.2.jar

\blackboard\systemlib\jnet-1.0.2.jar

\blackboard\systemlib\jsse-1.0.2.jar

2. Add the following to the JAVA_HOME/jre/lib/security/java.security file:security.provider.1=sun.security.provider.Sun

security.provider.2=com.sun.net.ssl.internal.ssl.Provider

3. If there are already security providers listed, and the first one is sun.security.provider.Sun,a security.provider.X entry should be added to the end of the list.

4. Import the signed public SSL certificate. Administrators configuring a fresh install of BlackboardLearn should import a certificate for each LDAP server to the applications server’s repository oftrusted certificates. This is done through the keytool utility.

Windows: http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html

UNIX: http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/keytool.html

How to Configure Contextual Error Messages for LDAPThe default error message does not report the cause of the error to the user when LDAP Authentication fails.Use the auth.type.ldap.context_factory property to display contextual error messages to users.

For each LDAP server configured, set the auth.type.ldap.context_factory property. This propertyreferences a class to use for creating contexts, which need to be server specific. The options are:

blackboard.platform.security.authentication.ResponseControlContextFactor

Any server that supports the Netscape password policy response controls spec - any breed of NetscapeDirectory Server including RedHat, SunONE, OpenLDAP, and others.

blackboard.platform.security.authentication.PasswordPolicyContextFactory

Any server that supports the IETF standard password policy attributes (passwordExpirationTime) but notresponse controls, for example, Novell Directory Server.

The PasswordPolicyContextFactory is used by default. If the PasswordPolicyContextFactoryis used the authenticationmodulemust be configured to use a valid privileged user (one that can search andaccess the passwordExpirationTime attribute of any user) for the proper error message to be shown.

Setting Up SSL for SIFThe connection between the ZIS and the SIF Agent can be secured using SSL. The settings are easilyconfigured in the bb-config.properties, however, SSL encryption requires a keystore and possibly atruststore from the ZIS server to function properly. The instructions below explain how to create and configure akeystore as well as how to configure a truststore from the ZIS server.

To learnmore about using SSLwith SIF integration, review the SifWorks ADK documentation available fromEdustructures.


9.1 S

P6 BETA D

RAFT

http://java.sun.com/j2se/1.3/docs/tooldocs/win32/keytool.html

http://java.sun.com/j2se/1.3/docs/tooldocs/solaris/keytool.html

http://www.edustructures.com/dev/index.html



SSL > Setting Up SSL for SIF

Creating and Configuring the Keystore

How to Create and Configure the Keystore on Windows1. Run the following from the command line:

%JAVA_HOME%\bin\keytool -genkey -v -keystore C:\blackboard_home\config\certs\SIFagent.ks -alias SIFagent -keyalg RSA -keysize 1024

2. The first prompt asks for a password for the keystore. The default password is "changeit".3. The next few prompts ask for information about the person creating the certificate. This information

will appear to users when they first access the Collaboration Tool over SSL. Users are prompted toaccept the certificate so it is important to provide accurate information so that users trust thecertificate. The information recorded is:

l First and Last Namel Organizational Unitl Organizationl City or Localityl State or Provincel Two-letter country code

4. The last prompt asks for the password for the certificate. This passwordmust be the same as thepassword entered in Step 2. Press ENTER to confirm that the same password will be used.

5. The keystore will be created in the specified directory.6. Create a Certificate Signing Request (CSR) for the SIF agent and sign the certificate.

%JAVA_HOME%\bin\keytool -certreq -keystore C:\blackboard_home\config\certs\SIFagent.ks -alias SIFagent -file SIFagent.csr

7. Submit the CSR to a certifying authority (CA) or self-sign the certificate.8. Download the server certificate and the CA certificate and copy them to the ZIS server.9. Import the server certificate into the Blackboard server keystore.

%JAVA_HOME%\bin\keytool -import -alias NAMEcaroot -file C:\blackboard_home\config\certs\NAME.cer -keystore C:\blackboard_home\config\certs\SIFagent.ks

keytool -import -alias SIFagent -file C:\blackboard_home\config\certs\SIFagent.cer -keystore C:\blackboard_home\config\certs\SIFagent.ks

keytool -list -keystore C:\blackboard_home\config\certs\SIFagent.ks -storepasschangeit

10. Share the keystore with the ZIS server.

How to Create and Configure the Keystore on UNIX1. Create a directory within the blackboard directory to hold the certificate.

mkdir /blackboard_home/config/certs

cd /blackboard_home/config/certs

2. Create a keystore by running the following command and responding to the prompts:keytool -genkey -v -keystore SIFagent.ks -alias SIFagent -keyalg RSA -keysize1024


9.1 S

P6 BETA D

RAFT

SSL > Setting Up SSL for SIF

l Enter keystore password: changeitl What is your first and last name? first lastl What is the name of your organizational unit? Product Developmentl What is the name of your organization? Blackboard Incl What is the name of your city or locality?Washingtonl What is the name of your state or province? DCl What is the two letter country code for this unit? USl Is CN=first last, OU=Product Development, O=Blackboard Inc, L=Washington, ST=DC,

C=US correct? Yesl Enter key password for (RETURN if same as keystore password): RETURN

3. Create a Certificate Signing Request (CSR) for the SIF agent and sign the certificate.keytool -certreq -keystore SIFagent.ks -alias SIFagent -file SIFagent.csr

4. Submit the CSR to a certifying authority (CA) or self-sign the certificate.5. Download the server certificate and the CA certificate and copy them to the ZIS server.6. Import the server certificate into the Blackboard server keystore.

cd /blackboard_home/config/certskeytool -import -alias NAMEcaroot -file NAME.cer -keystore SIFagent.ks

keytool -import -alias SIFagent -file SIFagent.cer -keystore SIFagent.ks

keytool -list -keystore SIFagent.ks -storepass changeit

7. Share the keystore with the ZIS server.

Configuring TrustStore

How to Configure TrustStore on WindowsImport the ZIS server certificate into the SIF Agent Trusted keystore.

cd C:\blackboard_home\config\certs

%JAVA_HOME%\bin\keytool -import -v -alias SIFWorks -keystore Trusted.ks -file ZIS.cer

Trust this certificate? [no]: yes

%JAVA_HOME%\bin\keytool -list -keystore Trusted.ks -storepass changeit

This will create a new keystore containing the ZIS certificate, which will be trusted.

How to Configure TrustStore on UNIXImport the ZIS server certificate into the SIF Agent Trusted keystore.

cd /blackboard_home/config/certs

keytool -import -v -alias SIFWorks -keystore Trusted.ks -file ZIS.cer

Trust this certificate? [no]: yes

keytool -list -keystore Trusted.ks -storepass changeit

This will create a new keystore containing the ZIS certificate, which will be trusted.


9.1 S

P6 BETA D

RAFT

SSL > Setting Up SSL for the Collaboration Tool in Windows

Setting Up SSL for the Collaboration Tool in WindowsSetting up SSL to encrypt connections to Blackboard Learn does not secure the Collaboration Tool because theCollaboration Tool uses Tomcat, not Apache or IIS, to handle user connections and serve pages. Securing theCollaboration Tool requires using a separate SSL certificate with Tomcat.

Most Institutions do not need to worry about securing the Collaboration Tool because the Collaboration Tool isnot used to transmit sensitive data. It should also be noted that using SSLwith the Collaboration Tool slowsdown performance of the tool. Consider both the need for security and the performance slow down associatedwith applying SSL before deciding to use SSLwith the Collaboration Tool.

As part of the process, a keystore and a self-signed certificate are created. A keystore is a file that storescertificates. A self-signed certificate is a certificate created by you that is not submitted to a CertifyingAuthority.

Note: Macintosh users running Netscape, Internet Explorer, or Safari may use self-signed certificates toconfigure SSL. A pop-up warningmay appear during the process; select Continue to complete the process.If users would prefer to use a signed certificate see the Java documentation on keytools for information onobtaining a signed certificate and including it in the keystore.

In most cases, taking the extra step to go through a Certifying Authority is not necessary when securing theCollaboration Tool. Certifying Authorities are used to prove to users of aWeb site that the connection is secureand verified by a trusted third party. Users accessing the Collaboration Tool from your Blackboard Learnmostlikely do not require the validation of a third party before using the tool.

How to Configure the Collaboration Tool with a Self-signed Certificate1. Create a keystore.2. Configure Tomcat properties to use SSL encryption.

Load-Balanced ConfigurationsThe same certificate must be used on each server. For detailed instructions on how to install the samecertificate on each server, seeMicrosoft Knowledge Base article 310178 athttp://support.microsoft.com/default.aspx?scid=kb;en-us;310178&Product-win2000.

Services on eachWeb/application server must be restarted after changing the SSLChoice option.

How to Create the KeystoreAfter creation the keystore contains a self-signed SSL certificate specifically for Tomcat, <tomcat>. To createthe keystore and certificate, follow these steps:

1. Log on to theWeb/app server as the user that runs Blackboard Learn.2. Run the following from the command line:

%JAVA_HOME%\bin\keytool –genkey -storetype pkcs12 –alias tomcat –keyalg RSA –keystore <path_to_keystore>

The keystore will be created at the <path_to_keystore>.

3. The first prompt asks for a password for the keystore. The default password that Tomcat expectsis "changeit," but it is recommended that another password be used. Tomcat can be configuredlater to accept the new password.


9.1 S

P6 BETA D

RAFT

http://support.microsoft.com/default.aspx?scid=kb;en-us;310178&Product-win2000



SSL > Setting Up SSL for the Collaboration Tool in UNIX

4. The next few prompts ask for information about the person creating the certificate. This informationwill appear to users when they first access the Collaboration Tool over SSL. Users are prompted toaccept the certificate so it is important to provide accurate information so that users trust thecertificate. The information recorded is:


5. The last prompt asks for the password for the <tomcat> certificate. This passwordmust be thesame as the password entered in Step 2. Simply press ENTER to confirm that the same passwordwill be used.

The keystore will be created in the specified directory.

How to Configure Tomcat to Work with the SSL CertificateAfter creating the keystore and certificate, the last step is to edit the blackboard\config\bb-config.properties file. Follow these steps to edit the file to work with SSL:

1. Make a backup of the following file:blackboard\config\bb-config.properties

2. Keep it safe so that the original settings can be restored.3. Open the bb-config.properties file in Notepad or an XML editor.4. Find the following lines in the file and add the appropriate values.

bbconfig.collabserver.keystore.filename=

bbconfig.collabserver.keystore.password=

bbconfig.collabserver.portnumber.ssl.default=8443

bbconfig.collabserver.keystore.type=PKCS12

The keystore.typemust be set to PKCS12.

5. Save the file.6. Run PushConfigUpdates to apply the changes. To learnmore, see PushConfigUpdates.7. Test the system. When accessing the Collaboration Tool, a prompt should appear to accept the

certificate. After accepting the certificate, the Collaboration Tool will open and communications willbe secured using SSL encryption.

Setting Up SSL for the Collaboration Tool in UNIXSetting up SSL to encrypt connections to Blackboard Learn does not secure the Collaboration Tool because theCollaboration Tool uses Tomcat, not Apache or IIS, to handle user connections and serve pages. Securing theCollaboration Tool requires using a separate SSL certificate with Tomcat.

Most Institutions do not need to worry about securing the Collaboration Tool because the Collaboration Tool isnot used to transmit sensitive data. It should also be noted that using SSLwith the Collaboration Tool slowsdown performance of the tool. Consider both the need for security and the performance slow down associatedwith applying SSL before deciding to use SSLwith the Collaboration Tool.


9.1 S

P6 BETA D

RAFT


As part of the process, a keystore and a self-signed certificate are created. A keystore is a file that storescertificates. A self-signed certificate is a certificate created by you that is not submitted to a CertifyingAuthority.

Macintosh users running a Netscape or Internet Explorer browser will not be able to access the CollaborationTool if a self-signed certificate is used to configure SSL. The Safari Web browser will work with a self-signedcertificate.

If there areMacintosh users running Netscape or Internet Explorer browsers then use a signed certificate. If asigned certificate is preferred, see the Java documentation on keytools for information on obtaining a signedcertificate and including it in the keystore.

In most cases, taking the extra step to go through a Certifying Authority is not necessary when securing theCollaboration Tool and a self-signed certificate may be used. Certifying Authorities are used to prove to users ofaWeb site that the connection is secure and verified by a trusted third party. Users accessing the CollaborationTool from your Blackboard Learnmost likely do not require the validation of a third party before using the tool.

How to Configure the Collaboration Tool with a Self-signed Certificate1. Create a keystore.2. Configure Tomcat properties to use SSL encryption.

How to Configure the Collaboration Tool with a Signed CertificateClients who would like to use their existing SSL certificate should follow these steps.

1. Convert the server.key and server.crt into a PKCS12 keystore using OpenSSL.openssl pkcs12 -export -out keystore.pkcs12 -in /path/to/server.crt

-inkey /path/to/server.key

2. This will prompt for a keystore password. The keystore will be created as keystore.pkcs12 inthe current directory. Move this to an appropriate location.

3. Use the keystore and certificate in the steps below that cover editing the bb-config.properties fileso that Tomcat uses SSL.

How to Create the KeystoreAfter creation, the keystore contains a self-signed SSL certificate specifically for Tomcat, <tomcat>.

To create the keystore and certificate, follow these steps:

1. Log on to theWeb/app server as the user that runs Blackboard Learn.2. Run the following from the command line:

%JAVA_HOME%\bin\keytool –genkey -storetype pkcs12 –alias tomcat –keyalg RSA –keystore path_to_keystore

The keystore will be created at the path_to_keystore.

3. The first prompt asks for a password for the keystore. The default password that Tomcat expectsis "changeit”, but it is recommended that another password be used. Tomcat can be configuredlater to accept the new password.

4. The next few prompts ask for information about the person creating the certificate. This informationwill appear to users when they first access the Collaboration Tool over SSL. Users are prompted toaccept the certificate so it is important to provide accurate information so that users trust thecertificate. The information recorded is:


9.1 S

P6 BETA D

RAFT



5. The last prompt asks for the password for the <tomcat> certificate. This passwordmust be thesame as the password entered in Step 2. Simply press ENTER to confirm that the same passwordwill be used.

6. The keystore will be created in the specified directory.

How to Configure Tomcat to Work with the SSL CertificateAfter creating the keystore and certificate, the last step is to edit the /blackboard/config/bb-config.properties file. Follow these steps to edit the file to work with SSL:

1. Make a backup of the /blackboard/config/bb-config.properties file.2. Keep it safe so that the original settings can be restored.3. Open the bb-config.properties file in an editor.4. Find the following lines in the file and add the appropriate values.

bbconfig.collabserver.keystore.filename=

bbconfig.collabserver.keystore.password=

bbconfig.collabserver.portnumber.ssl.default=8443

bbconfig.collabserver.keystore.type=PKCS12

The keystore.typemust be set to PKCS12

5. Save the file.6. Run PushConfigUpdates to apply the changes. To learnmore, see PushConfigUpdates.7. Test the system. When accessing the Collaboration Tool, a prompt should appear to accept the

certificate. After accepting the certificate, the Collaboration Tool will open and communications willbe secured using SSL encryption.


9.1 S

P6 BETA D

RAFT

SIF > About SIF

SIF

About SIF

Exchanging and Synchronizing DataThe School Interoperability Framework (SIF) is an industry initiative to develop a scalable solution for dataexchange, synchronizing data entered in one system with the data in other systems within the SIF framework.A SIF implementation is a distributed networking system that consists of a Zone Integration Server (ZIS) andone or more SIF integration agents that communicate with the ZIS, all organized into a zone. The size of thezone is flexible and could consist of a single building, a school, a small group of schools, or a district.

The ZIS is responsible for all access control and routing within the system. It provides integration services to allthe agents registered with it so that the agents can subscribe to data changes that occur within the zone orpublish data changes out into the zone. For example, if a user’s phone number is changed on one of the agentsystems, the agent can publish this change to the ZIS, and any other agents that have subscribed to userinformation data changes will then receive the new phone number from the ZIS.

In SIF, an agent never talks to another agent directly. Instead, an agent communicates with the ZIS whichmanages the connection to the other agent. By having the ZIS manage the routing responsibilities, complexcommunications can occur between agents that have no direct information about each other. The ZIS acts asthe trusted intermediary that brokers the data exchange.

The Blackboard SIF AgentThe Backboard SIF Agent registers with a ZIS and indicates the data Blackboard Learn can receive. ZIS tracksthe data that the Blackboard SIF Agent can receive and forwards amessage to the Blackboard SIF Agent ifanother agent has posted an applicable data change to the ZIS.

The Blackboard SIF Agent conforms to SIF standards for receiving updates to user information data from theZIS. It subscribes to data changes but does not publish data changes. SIF communication is automated. Oncethe Blackboard SIF Agent is configured, it automatically updates information when notification of a data changeis received from the ZIS. The frequency of updates is configurable.

Some important points about the Blackboard SIF Agent:

l The SIF Agent will not transmit information to the ZIS server, it will only receive information.l The SIF Agent will add, modify, or delete user records. It will not make changes to other data.l The SIF Agent is configured to listen for data from the ZIS at intervals using the Pull protocol.l The ZIS server owns the data sent according to the Blackboard Learn database. Ensure that this

does not conflict with established integration solutions using Snapshot or the Blackboard integrationAPIs.

Setting Up the Blackboard SIF AgentThe Blackboard SIF agent is installed with Blackboard Learn. Configuring the SIF Agent to receive informationfrom the ZIS is accomplished by activating the Agent in the service-config.properties file and editingthe Agent properties in the bb-config.properties file.


9.1 S

P6 BETA D

RAFT

SIF > Setting Up the Blackboard SIF Agent

How to Edit the service-config.properties File1. Open /blackboard_home/config/service-config.properties

2. To activate the SIF Agent, uncomment the following lines:############################ SIF Service ################################

blackboard.service.name.sifservice=blackboard.platform.sif.SIFAgentService

blackboard.service.impl.sifservice=blackboard.platform.sif.SIFAgentService

blackboard.service.sifservice.param.config=config/bb-sif-agent-config.xml

blackboard.service.sifservice.initlevel=17

Uncommenting these lines of code will cause the application to attempt to communicate with a ZISserver using the parameters defined in the bb-config.properties file.

How to Configure Settings in the bb-config.properties File1. Open /blackboard_home/config/bb-config.properties.2. Edit the file using the properties int he following table.


bbconfig.sif.pull.frequency Determines how often the SIF Agent will retrieve updates fromthe ZIS. This value is expressed in seconds.

bbconfig.sif.zone Identifies the zone to which the SIF Agent subscribes.

bbconfig.sif.host Identifies the ZIS server.

bbconfig.sif.port The port used to listen for communication from the ZIS.

bbconfig.sif.protocol This must be set to HTTP for an unencrypted connection orHTTPS to use SSL to encrypt communication between the ZISand the SIF Agent.

bbconfig.sif.keystore The keystore is a certificate used to identify the SIF agent.refers to the keystore file that our agent uses to identify itself(in the handshake process of the HTTPS protocol typeconnection, the ZIS will read this keystore from the agent andthe agent will also read the ZIS’s self-identifying keystore).

bbconfig.sif.keystore.password Password for the keystore.

bbconfig.sif.truststore The truststore is a certificate used to identify trusted sources.refers to the keystore file that says who our agent trusts; thiskeystore file is created from importing the ZIS’s self-identifyingcertificate, so that in the handshake process our agent canmatch the ZIS’s keystore with who we say we trust in ourtruststore file.

bbconfig.sif.truststore.password Password for the truststore.


9.1 S

P6 BETA D

RAFT

SIF > Setting Up the Blackboard SIF Agent


bbconfig.sif.authlevel The SIF Authentication levels we set for bbconfig.sif.authlevelmeans the following to the ZIS receiving the connectionmessage:

0 - This agent is not sending a certificate to identify itself1 - This agent has a valid certificate to send to identify itself2 - This agent has a valid certificate to send to identify itselfAND it got it from a source the ZIS trusts (trusted certificateauthority)

For level 0, the SIF Agent is not authenticating itself to the ZIS.In this instance, use the HTTP protocol to connect and do notset a keystore or a truststore. For levels 1 and 2, the HTTPSprotocol must be used to connect and the keystore andtruststore parameters set.

When creating the keystore files, the ZIS must be configured totrust the agent’s certificate. This is done by importing theagent’s certificate into the ZIS’s “Trusted Agent Certificates”section.

If the ZIS trusts the SIF Agent certificate, the agent willsuccessfully connect to the ZIS on level 2 authenticationbecause the self-identifying keystore is one that the ZIS trusts.If the ZIS does not trust the agent’s certificate, then connectionat level 2 would fail. However, level 1 authentication level willstill allow the agent to successfully connect to the ZIS if the ZISwere to not trust our agent’s certificate. This is because at level1, the agent only needs a valid certificate to identify itself—thecertificate does not have to be one that the ZIS trusts.

Example:

#####################################################################

#################### SIF configuration settings #####################

#####################################################################

bbconfig.sif.pull.frequency=30000

bbconfig.sif.zone=Bb-SIF-Test

bbconfig.sif.host=ZIS_SERVER.BLACKBOARD.EDU

bbconfig.sif.port=7443

bbconfig.sif.protocol=https

bbconfig.sif.keystore=/blackboard_home/config/certs/SIFagent.ks

bbconfig.sif.keystore.password=changeit

bbconfig.sif.truststore=/blackboard_home/config/certs/Trusted.ks

bbconfig.sif.truststore.password=changeit

bbconfig.sif.authlevel=2

3. Run the PushConfigUpdates command to apply the changes.

Note: The PushConfigUpdates command has been enhanced to improve systemmanagement. PushConfigUpdates automatically updates the admin data in the database byreading the value in the config.xml. It automatically pushes the changes of the databasehostname and port, instance name, and externally visibleWeb server hostname to the database. Tolearnmore, see PushConfigUpdates.


9.1 S

P6 BETA D

RAFT

SIF > Using Data Mapping

UNIX:

/blackboard_home/tool/admin/PushConfigUpdates.sh

Windows:

C:\blackboard_home\tool\admin\PushConfigUpdates

The values in bb-config.properties are written to /blackboard_home/config/bb-sif-agent-config.xml.

4. Check the log/blackboard_home/logs/tomcat/sif-log.txt to verify the connection.2009-08-12 17:29:35,833 DEBUG [ADK.Agent$Bb-SIF-Test] Polling for nextmessage...2009-08-12 17:29:35,986 DEBUG [ADK.Agent$Bb-SIF-Test] Send SIF_SystemControl2009-08-12 17:29:35,987 DEBUG [ADK.Agent$Bb-SIF-Test] MsgId:7CDD8B1AA327B2F646030FDE3B72DC5F2009-08-12 17:29:35,989 DEBUG [ADK.Agent$Bb-SIF-Test] Sending message (646 bytes)2009-08-12 17:29:36,095 DEBUG[ADK.Agent$Bb-SIF-Test] Expecting reply (489 bytes)2009-08-12 17:29:36,095DEBUG [ADK.Agent$Bb-SIF-Test] Received reply (489 chars)2009-08-12 17:29:36,100DEBUG [ADK.Agent$Bb-SIF-Test] Receive SIF_Ack (Status = 9; Errors = 0)2009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] MsgId:7166CC00636B004C4A81061B23E137A72009-08-12 17:29:36,100 DEBUG [ADK.Agent$Bb-SIF-Test] OrgId: 7CDD8B1AA227B2F646030FDE3B72DC5F2009-08-12 17:29:36,100DEBUG [ADK.Agent$Bb-SIF-Test] No messages waiting in agent queue

Sample bb-sif-agent-config.xml FileThe following example defines the sif-agent-config.xml file. Please remember not to make any changesdirectly to this file. Instead, edit the parameters in the bb-config.properties file and runPushConfigUpdates to make changes.

 <agent-listing> <!--top level container. Multiple agentscan be registered--!> <agent-entryclass="blackboard.platform.sif.agent.StudentPersonalProvider" version="70">

<!--declaration of agent implementation class. Full class name must be provided Versionis just meta-data--!>

<connection class="blackboard.platform.sif.connect.SIFPullConnection" > <!--declaration of connection implementation class. SIFPullConnection and SIFPushConnectionavailable--!> <property name="frequency" value ="30000" /> <!-- properties arecustom per connection type. For “PULL” you specify the frequency the agent wakes up todo a pull--!> </connection> <zis> <!--zis represents data detailing location andmeans to interact with the server. --!> <zone name="Bb-SIF-Test" /> <!--SIF Zone tobe used--!> <host name="10.10.107.77" port="7443"/> <!--ZIS server host and port toattach to. --!> <transport protocol="https"> <!--Actual protocol to be used. Can beeither “http” or “https” if not recognized “http” will be used. --!> <propertyname="keystore" value ="C:/myURL.com/testing/sif-test-app/cert/Agent.ks" /><property name="keystorepassword" value ="mypassword" /> <propertyname="truststore" value ="C:/myURL.com/testing/sif-test-app/cert/Trusted.ks" /><property name="truststorepassword" value ="changeit" /> <!--The aboveproperties represent location of certificate stores and their corresponding passwords. --!> <property name="clientauth" value ="true" /> <!-- Controls whether the ZISserver should require SSL certificate exchange during an operation--!> <propertyname="authlevel" value ="2" /> </transport> </zis> </agent-entry> </agent-listing>

Using Data MappingSIF integration passes user data from other system to the Blackboard system through the ZIS server.

The table below outlines the data that is passed andmaps the ZIS value to the corresponding BlackboardValue.


9.1 S

P6 BETA D

RAFT

SIF > Using Data Mapping

SIF Object

BlackboardUserInformation Description

RefID BATCH_UID Required field in Bb. Event will fail if this field cannot bepopulated. Max= 64. Accepts multi-byte.

Name/FirstName FIRSTNAME Required field in Bb. Event will fail if this field cannot bepopulated and the event is trying to create a new user. Max=100. Accepts multi-byte.

Name/MiddleName MIDDLENAME Max= 100. Accepts multi-byte.

Name/LastName LASTNAME Required field in Bb. Event will fail if this field cannot bepopulated and the event is trying to create a new user. Max=100. Accepts multi-byte.

Email EMAIL Max= 100. Must contain "@" and "."

USER_ID Required field in Bb. For Add Event, will be the same asBATCH_UID. Max= 50. For creating new users, since theusername will be created from the BATCH_UID and theBATCH_UID allows a max of 64, if the BATCH_UID has over50 characters, then the username cannot be created due to thelimitation and the event will fail. Accepts multi-byte.

PASSWD Required field in Bb. For Add Event, will be the same asBATCH_UID. Max= 32

Demographics/Gender GENDER SIF M = Bb MaleSIF F = Bb FemaleSIF U = Bb Not Disclosed

Demographics/Birthdate BIRTHDATE Datetime field type. Max= 8

StudentAddress/Address/Street/Line1

STREET_1 Max= 100. Accepts multi-byte.

StudentAddress/Address/Street/Line2 STREET_2 Max= 100. Accepts multi-byte.

StudentAddress/Address/City CITY Max= 50. Accepts multi-byte.

StudentAddress/Address/ StatePr STATE Max= 50. Accepts multi-byte.

StudentAddress/Address/PostalCode ZIP_CODE Max= 50. Accepts multi-byte.

StudentAddress/Address/Country COUNTRY Max= 50. Accepts multi-byte.

PhoneNumber H_PHONE_1 Max= 50. Accepts multi-byte.

PUBLIC_IND Required field in Bb. For Add Events, will default to N.

EMAIL_IND Required field in Bb. For Add Events, will default to N.

ADDRESS_IND Required field in Bb. For Add Events, will default to N.

WORK_IND Required field in Bb. For Add Events, will default to N.

PHONE_IND Required field in Bb. For Add Events, will default to N.

SYSTEM_ROLE Required field in Bb. For Add Events, will default to None.

INSTITUTION_ROLE

Required field in Bb. For Add Events, will default to Student.

ROW_STATUS Required field in Bb. For Add Events, will default to 0(enabled).


9.1 S

P6 BETA D

RAFT

API > About the Event Driven API Architecture

API

About the Event Driven API ArchitectureThe API is a collection of java classes and objects that move data from the institution systems into BlackboardLearn. Concrete data from the institution systems are encapsulated as java objects. Themethods contained inthe java classes determine how the data is input into Blackboard Learn. The data input is controlled bypersisters that process the appropriate method, convert the object into data that can be input into BlackboardLearn database, and then input that data according to themethod called.

Entities and PersistersThere are twomain types of objects in the API: entities (objects) and persisters (actions). Entities include theobjects that represent data in the system, such as users. Persisters are behind-the-scenes methods thathandle the storage of the entities into a persistent store or transient data format.

OperationsAll data classes havemethods to handle persistence actions. The following persistence operations aresupported:

l Insert: Inserts a record into the Blackboard Learn database.l Update: Updates an existing record in the Blackboard Learn database.l Save: Updates an existing record if it already exists. Otherwise, if it does not exist, inserts the record

in the Blackboard Learn database.l Remove: Purges the record from the Blackboard Learn database.l Change Key: (Person andGroup, Course, andOrganization) Changes the primary key. This will

automatically update any relatedMemberships of the changed keys.

How to Create an ObjectTo create an object in the system, instantiate a corresponding entity, set attributes on the object, and then call apersister method (insert, update, save, delete).

PersistersThe following Persisters are found in the Event Driven API:

CourseSitePersister

OrganizationPersister

EnrollmentPersister

OrganizationMembershipPersister

StaffStudentPersister

PersonPersister

CourseCategoryPersister

OrganizationCategoryPersister

CourseCategoryMembershipPersister

OrganizationCategoryMembershipPersister


9.1 S

P6 BETA D

RAFT

API > About Event Driven APIs

PortalRolePersister

Persist methods include changeKey, insert, remove, save, update, clone. Change key is not relevant formembership type items. Clone is only relevant for Coursesite/Organization. More information about Persistmethods can be found in the API specifications.

LoadersThe following Loaders are found in the Event Driven API:

SourseSiteLoader

OrganizationLoader

EnrollmentLoader

OrganizationMembershipLoader

StaffStudentLoader

PersonLoader

CourseCategoryLoader

OrganizationCategoryLoader

CourseCategoryMembershipLoader

OrganizationCategoryMembershipLoader

PortalRoleLoader

Loadmethods include load by batch_uid and load by template. More information about Loadmethods can befound in the API specifications.

Data Source Loader and PersisterThe following Data Source Loader and Persister are found in the Event Driven API:

DataSourceLoader

loadAll()

loadAdminObjectCount()

loadAllAdminObjectCounts()

loadByBatchUid()

DataSourcePersister

create()

disableAdminObjectsByDataType()

disableAllAdminObjects()

modify()

purgeAdminObjectsByDataType()

purgeAllAdmiObjects()

purgeSnapshotSessions()

removeByBatchUid()

About Event Driven APIsThe Blackboard Learn Event Driven API is used to programmatically push the following data into theBlackboard Learndatabase from an external system:


9.1 S

P6 BETA D

RAFT

API > Using the API and Determining Relationships

l Userl Coursel Organizationl Enrollmentl Staff Studentl Organizationmembershipl Course andOrganization categoryl Course andOrganization category membership

The collaboration between the entity and the persistence classes is the process by which data is obtained fromthe institution systems. An instance is created for that data, and input into the Blackboard Learn database as adata record.

The intended audience includes developers creating data integration solutions for the Blackboard Learn. Codesamples can be found in the Resources folder.

Note: The Data Integration API Specifications describe the packages, classes, and objects of the EventDriven API in systemlib/cms-admin.jar.

Using the API and Determining RelationshipsWhen using the API, there are specific steps than need to be followed to determine the relationships betweenthe entity and the persistence classes.

How to Determine RelationshipsFollow the steps below to determine the relationships between the entity and persistence classes.

1. The programmust first initialize the BbServiceManager object. Themethod call isblackboard.platform.BbServiceManager.init( serviceConfig ); whereserviceConfig is a java.io.File object. This object represents a link to the configuration fileon the operating system. The file is a detailed list of all services that are active on the instance ofthe servicemanager as well as any of their configuration files.

The BbServiceManager object is only initialized once for each execution of the application.

A virtual host is also needed for proper setup. A virtual host can be obtained by first getting theVirtual InstallationManager usingBBServiceManager.lookupService(VirtualInstallationManager.class). TheVirtual InstallationManager has a getVirtualHost(String id)method which returns thevirtual host.

Next, the ContextManager must be retrieved usingBBServiceManager.lookupService(ContextManager.class). Finally, the context canbe set by calling the ContextManager’s setContext()method and passing in the virtualhost as an argument.

The following code sample assumes a “SERVICE_CONFIG_DIR” and “VIRTUAL_HOST_KEY”properties will be set, probably through –D parameters if it is used in a command line application.The SERVICE_CONFIG_DIR should be set to the full path of the Blackboard config directory,while the VIRTUAL_HOST_KEY needs to be the virtual installation you wish to test, by default it isbb_bb60.

// Initialize the BbServiceManager and set the context


9.1 S

P6 BETA D

RAFT

API > Using the API and Determining Relationships

try

{

blackboard.platform.BbServiceManager.init(System.getProperties().getProperty("SERVICE_CONFIG_DIR") + "service-config-snapshot-jdbc.properties");

// The virtual host is needed to establish the proper database context.

VirtualInstallationManager vm = (VirtualInstallationManager)

BbServiceManager.lookupService(VirtualInstallationManager.class);

String vhostUID = System.getProperty("VIRTUAL_HOST_KEY", "bb_bb60");

VirtualHost vhost = vm.getVirtualHost(vhostUID);

vhost = vm.getVirtualHost(vhostUID);

if(vhost == null)

{

throw new Exception("Virtual Host '" + vhostUID + "' not found.");

}

// Now that the vhost is set we can set the context based on that vhost

ContextManager cm = (ContextManager)BbServiceManager.lookupService(ContextManager.class);

Context context = cm.setContext(vhost);

}

catch(Exception e)

{

System.out.println("Exception trying to init the BbPersistenceManager\n "+ e.toString() + "..exiting.\n");

System.exit(0);

}

2. The controller creates an entity object and sets its attributes.

The following is an example of how to get a Course site:

blackboard.admin.data.course.CourseSite site=new

blackboard.admin.data.course.CourseSite();

3. The controller requests a persist action off the Loader / Persister.CourseSiteLoader cLoader=

(Course-Site-Loader)BbServiceManager.getPersistenceService().getDbPersistenceManager().getLoader(CourseSiteLoader.TYPE);

CourseSitePersister cPersister=

(Course-Site-Persister)BbServiceManager.getPersistenceService().getDbPersistenceManager().getPersister(CoursesSitePersister.TYPE);

PersistenceManager.getLoader=PersonPersister.Default.getInstance()

4. The controller catches any persistence exceptions that occur.

Steps 2, 3, and 4may be repeated for different entities and different persist actions as needed.


9.1 S

P6 BETA D

RAFT

API > About the Persister Package

About the Persister PackageThis topic reviews the persister package found in the Event Driven API. For themost complete and up-to-dateinformation about packages and classes, refer to the java docs included with the API.

Persistence PackageThe persistence package provides a framework to handle the insert, update, save, and delete for the entityobjects. The framework includes:

l BbServiceManager: This class handles the coordination of Blackboard Learn enabled services.l PersistenceService: This class is a singleton, an object only intended to exist once, that

manages the different persistence context for the entity objects.l DbPersistenceManager: This class maintains the reference points for each individual

loader/persister. An instance of any persister/loader is requested through it.l PersisterInterfaces: This includes the PersonPersister, CoursesitePersister, and

so forth.

blackboard.platform.BbServiceManager.init( serviceConfig,bbprops );

blackboard.platform.persistence.PersistenceService pService =BbServiceManager.getPersistenceService().

blackboard.persist.BbPersistenceManager bManager = pService.getDbPersistenceManager()

CoursesiteLoader cLoader= (CoursesiteLoader)bManager.getLoader(CoursesiteLoader.TYPE);

PersistenceManager.getLoader=PersonPersister.Default.getInstance()

The user must initialize the BbServiceManager before attempting any persistence of the admin data objects.After BbServiceManager is initialized the appropriate loader/persister must be used according to the datatype the programmer intends tomanage.


9.1 S

P6 BETA D

RAFT

Tools > Using Command Line Tools

Tools

Using Command Line ToolsBlackboard Learn includes a set of system administration tools that must be run from the command line. Tryingto execute a utility by clicking the .bat file in theWindows GUI will return errors and possibly cause the systemto stop functioning.

This topic covers each tool and the syntax to invoke the tool. All of the commands described in this topic arefound in the blackboard_home/tools/admin directory.

PurgeAccumulatorEvery 30 days an automatic process runs that synchronizes the data in the stats database with the data in themain database and then deletes the statistical data from themain database that is more than 30 days old. Thisprocess can be run at any time using the PurgeAccumulator tool. The PurgeAccumulator tool can alsobe used to delete data from the statistics database.

Windows:

PurgeAccumulator.bat commandDatabase_Namedays_or_date

UNIX:

PurgeAccumulator.sh commandDatabase_Namedays_or_date


command purge-live: Takes data from Blackboard Learn database and syncs with tables in the statisticsdatabase. After synching, it purges statistical data in the main database that is older than the numberof days or date set.purge-stats: Goes to stats DB and purges all data older than the last x days or older than a specificdate.

Database_Name

Enter the name of the main database (bbuid) of the database to be purged.

days_or_date

The number of days (from the current date) that should not be processed by the PurgeAccumulatortool. It is also possible to set a date in yyyy-mm-dd format. Only data older than the date will bepurged.

PushConfigUpdatesThis tool updates the configuration according to the settings in the bb.config.properties file.

WARNING! Running this commandwill redeploy all of the properties files. If any customizations havebeenmade to the properties files, they will be lost.

The PushConfigUpdates command has been enhanced to improve systemmanagement. Now, thePushConfigUpdates automatically updates the admin data in the database by reading the value in theconfig.xml. It automatically pushes the changes of the database hostname and port, instance name, andexternally visibleWeb server hostname to the database. Running this tool always restarts the services toreflect the changes.


9.1 S

P6 BETA D

RAFT

Tools > Using Command Line Tools

The first operation of this tool will replace the existing template files, copying the original template files to atime-stamped sub-directory of blackboard_home/backups/templates/time_stamped. Use thesefiles to retrieve and re-apply any local customizations.

The second operation of this tool is Tomcat specific and requires that Custom Authentication be disabled tosuccessfully complete this operation. The .jar files from apps/tomcat/server/lib/directories will beloaded rather than from blackboard_home/systemlib/. Be aware that any .jar file found in the directorywill be loaded at Tomcat startup. This operation is controlled by the .classpath files located inconfig/tomcat/classpath. Any changes to the Tomcat configuration files or startup scripts must bemade to the templates in the config/tomcat/ directory, in particular this applies to additional MIME types added to the web.xml file. Touch points are files such as web.xml, server.xml, startup scripts, andconfiguration files used in clustered Tomcat environments.

The third operation updates the BBLEARN.SYSTEM_REGISTRY (legacy: BB_BB60.SYSTEM_REGISTRY) database table with the configuration changes. The current performance parameters for the Application serverare recorded in the BBLEARN_ADMIN.CONFIG.REGISTRY (legacy: BBADMIN.CONFIG.REGISTRY)database table.

The final operation configures content management, which includes license verification, connection informationupdate, then pushing the new information to the database. The version of each database schema is thenchecked and updated if necessary.

Windows:

blackboard_home\tools\admin\PushConfigUpdates.bat

UNIX:

blackboard_home/tools/admin/PushConfigUpdates.sh

When using the PushConfigUpdates tool inWindows, it is very important that the tool is run on the commandline rather than double-clicking the file from windows explorer. The command line will execute the tool inverbosemode, displaying important messages.

RotateLogsThis tool processes a log rotation outside the scheduled log rotations configured through theManage LogRotation page. The tool stops all necessary services and starts the services after the rotation is finished.

Windows:

blackboard_home\tools\admin\RotateLogs.bat

UNIX:

blackboard_home/tools/RotateLogs.sh

This command does not take any arguments. If logs aremanually rotated using this tool it will not interrupt theregular intervals. However, the logs that were rotatedmanually will not be included in the archive files createdat the regularly scheduled rotation.

For example, if the log rotation is set at 30 days and the logs aremanually rotated after 15 days, only the last 15days of logs will be included in the archives at the next scheduled log rotation.

ServiceControllerThis tool is used to start and stop services.

Windows:

blackboard_home\tools\admin\ServiceController argument


9.1 S

P6 BETA D

RAFT

Tools > Using Command Line Tools with Content

UNIX:

blackboard_home/tools/admin/ServiceController argument

An error may occur when running this tool if a symbolic link in /bin to the correct location of the bash shelldoes not exist. Run the following command to create this link:

ln –s /bin/bash /usr/local/bin/bash

This assumes that bash resides in /usr/local/bin/bash. If it resides elsewhere, please use that pathwhen creating the symbolic link.


services.start Starts all the services related to Blackboard Learn.

services.stop Stops all the services related to Blackboard Learn.

services.restart Stops and immediately starts the services related to Blackboard Learn.

services.appserver.start Starts the bb-tomcat service.

services.appserver.stop Stops the bb-tomcat service.

services.appserver.restart Stops and immediately starts the bb-tomcat service.

services.webserver.start Starts the IIS or Apache Web service.

services.webserver.stop Stops the IIS or Apache Web service.

services.webserver.restart Stops and immediately starts the IIS or Apache Web service.

SystemInfoThis commandwill create a detailed report of system settings. The report can be viewed in the blackboard_home/logs/system-info directory. The name of the report will be named yyyymmdd_OS.log. Where OSis the operating system and yyyymmdd is the date in year-month-day format.

Windows:

blackboard_home\tools\admin\SystemInfo.bat

UNIX:

blackboard_home/tools/admin/SystemInfo.sh

Using Command Line Tools with ContentBlackboard Learn includes a set of system administration tools for content management that must be run fromthe command line.This topic describes each tool and gives examples of the syntax to invoke the tool. All of thecommands described in this topic are found in the blackboard/apps/bbcms/bin directory. OnWindowsOperating Systems they are .bat files; on UNIX Operating Systems they are .sh files. An error will appear if acommand is not successful. If nothing is reported the command processed successfully.

Note: When creating directories, do not insert the following characters into the directories for users, folders, orfiles:

\ / : * ? " < > |

Otherwise, these command lines cannot be executed.


9.1 S

P6 BETA D

RAFT


Using Spaces in Directory NamesIf a source path or destination path includes spaces when using a command line tool, quotes must be used toenclose the entire path. The following are some examples:

file-import C:\Folder1 /users/Biology/Week1

file-import "C:\Folder 1" /users/Biology/Week1

file-import C:\Folder1 "/users/Biology/Week 1"

file-import "C:\Folder 1" "/users/Biology/Week 1"

file-importThis tool will import the files and directories from the source path on file system into the destination path inBlackboard Learn. The destination pathmust already exist for this operation to work. The tool can only be usedto import directories. It cannot be used to import individual files. The tool will automatically import allsubdirectories from the source folder.

Example: Syntaxfile-import local directory on File System destination directory in Blackboard Learn

Example: Windowsfile-import.bat "c:\inst files" /institution/blackboard

Example: UNIXfile-import.sh /user/local/blackboard /institution/blackboard

Files may not bemoved through cutting and pasting or copying files in the operating system; the command linetool (or the user interface) must be used for this operation.

create-all-user-directoriesThis tool creates folders in the /users directory for all users who are entitled to a user folder. After creating userdirectories, user folders can be pre-populated with content before the user even enters the Content Collection.If this tool is not run, the user folder is created the first time a user accesses the Content Collection tab.

Users who are entitled to folders are selected by the Administrator. They are granted virtual hard drive space onthe system and their Institution Roles are selected. This must be set up before the Administrator uses this tool.This allows the administrator to pre-populate these folders.

Example: Syntaxcreate-all-user-directories

create-all-courseorg-directories

When this tool is run, all of the following directories are created:

l Course folders in Coursesl organization folders in Organizationsl Course folders in e-Reserves

This allows folders to be created before the folders are accessed by users. The Courses and organizationsmust already be created in the Blackboard Learn for the folders to be created in the Content Collection. Theability to create folders corresponds to the availability to the /courses and /organization areas; if, for instance,/courses is not available, then folders cannot be created for /courses.


9.1 S

P6 BETA D

RAFT


Example: Syntaxcreate-all-courseorg-directories

create-directoryThis tool creates a directory at the given path. The parent directory must exist beforehand. This tool cannotcreate top level directories and will only create a directory in one of the existing top level folders. This toolcannot create directories in directories where subdirectories are automatically created, such as /users,/courses, /library/eReserves/, and /orgs; however, it may be used to create subdirectories under theseautomatically created folders (for example, /users/administrator/new folder).

Example: Syntaxcreate-directory directory name

Example: Windowscreate-directory.bat /institution/Public/Media

Example: UNIXcreate-directory.sh /institution/Public/Media

Directories cannot be created through cutting and pasting or copying folders in the operating system; thecommand line tool (or the user interface) must be used for this operation.

create-user-directoryThis tool creates a directory for a user with a given username, and assigns appropriate permissions for thatuser. The user must already exist in Blackboard Learn.

Example: Syntaxcreate-user-directory username

Example:create-user-directory username

This command can also be used to batch create user directories. The users must be separated by a comma.

Example:create-user-directory admin, root_admin

User folders cannot be created through cutting and pasting or copying folders in the operating system; thecommand line tool (or the user interface) must be used for this operation.

create-course-directoryCreates a directory for a Course with a given Course ID in /courses/ and assigns appropriate permissions forthat Course and roles. An example of the Course ID is, bio101, not the database integer key or the name of theCourse. If the Course ID corresponds to a Course (not anOrganization) then a directory is also created in/library/eReserves. The Coursemust already exist in Blackboard Learn.

Example: Syntaxcreate-course-directory course ID


9.1 S

P6 BETA D

RAFT


Example:create-course-directory history100

Course directories cannot be created through cutting and pasting or copying folders in the operating system; thecommand line tool (or the user interface) must be used for this operation.

set-directory-quotaAssigns a quota to a directory, or can be used to assign an unlimited amount of space. This tool may not beused on the root directories, such as /courses or /institution, but may be used on folders within these areas.This tool alsomay not be used on the directory /library/eReservers.

Example: Syntaxset-directory-quota path to directory quota in MB

Example:set-directory-quota /users/jsmith 30

set-directory-quota /users/jsmith 30

Example: To set unlimited quotaset-directory-quota /users/jsmith NONE

user-access-controlThis tool gives a user corresponding permissions to a file/directory at the given path. The user must exist inBlackboard Learn and the pathmust correspond to an existing file/directory. A user with all permissions isindicated by 'rwdm'. Read and write permission is indicted by 'rw'. Do not include any spaces between theletters. No permissions may be specified by using ‘none’, for example, to remove all permissions for a givenuser.

Example: Syntaxuser-access-control file or directoryuser IDpermission

Where permission is ‘r’ – read, ‘w’ – write, ‘d’ – delete, or ‘m’ –manage.


Example:user-access-control /institution jsmith rwdm

user-access-control /institution jsmith rwdm

course-access-controlThis tool gives a Course corresponding permissions to a file/directory at the given path. The Coursemust existin Blackboard Learn and the pathmust correspond to an existing file/directory. No permissions may bespecified by using ‘none’, for example, to remove all permissions for a given Course.

Example: Syntaxcourse-access-control file or directoryCourse IDpermission


Example:course-access-control /institution history rwdm


9.1 S

P6 BETA D

RAFT


course-role-access-controlThis tool gives a Course Role corresponding permissions to the file/directory at a given path. The Coursemustexist in Blackboard Learn. The pathmust correspond to an existing file/directory. No permissions may bespecified by using 'none', for example, to remove all permissions for a given role.

Example: Syntaxcourse-role-access-control file or directorycourse IDrolepermission

Where role is STUDENT, Instructor, TEACHING_ASSISTANT, COURSE_BUILDER, Grader, or GUEST andpermission is ‘r’ – read, ‘w’ –write, ‘d’ – delete, or ‘m’ –manage.

Example:course-role-access-control /institution history100 Instructor rwdm

full-text-index UPDATEThis tool is used tomanage the full text search index in the Content Collection. The full text search indexcreates an index of all terms in the documents and file names within the Content Collection.

This commandwill manually update the full text search index. If a time is not entered, the index will run until it iscomplete. There is an automated process for running this tool that may be configured through the SystemControl Panel.

Example: Syntaxfull-text-index UPDATE number of minutes to run

Example:full-text-index UPDATE 45

This commandwill run the full text search index for 45minutes.

full-text-index UNLOCKIf errors occur while the index is being built the index may become locked. This tool is used to unlock it. If thisoccurs, lock errors will appear in the error logs. The index may appear to be locked when another operation inthe system is running, This tool should not be used in this instance; this command should only be run if theAdministrator sees lock errors in the error logs.

Example: Syntaxfull-text-index UNLOCK

Example:full-text-index UNLOCK

Copy Files to CS ToolThe Copy Files to CS tool enables Administrators to copy content from aCourse in Blackboard Learn to a folderin the Content Collection. All files that have been attached to the Course will be copied to the ContentCollection; files from specific Course areas may not be selected. This tool can be used on all types of Courses;available Courses, Coursemade unavailable through the Administrator Panel and Courses disabled throughSnapshot.


9.1 S

P6 BETA D

RAFT

Tools > Data Source Management (DSM) Tool

Files from the Coursemay be copied to the Course folder in the Content Collection, or another folder that existswithin in the Content Collection.

This command copies the files from aCourse to the Course folder within the Content Collection. If a Coursefolder does not exist, one is automatically created.

Example: Syntaxcopy-course-files-to-cs courseid

Example:copy-course-files-to-cs History100

create-all-user-directoriesThis command copies the files from aCourse to another folder (not the Course folder) within the ContentCollection. The folder must exist within the Content Collection before running this command.

Example: Syntaxcopy-course-files-to-cs courseidpath to folder in the Content Collection

Example:copy-course-files-to-cs History100 "/users/jsmith/my documents/"

Data Source Management (DSM) Tool

About Data EntitiesA data entity is a type or group of data records that share the same attributes. An easy way to visualize a dataentity is to view it as a table, with attributes as columns and records as rows. Each record in an entity is definedby a unique identifier called a primary key, or a key.

Blackboard Learn data entities adhere to the IMS standards for data, making it possible to consistently mapdata entities from a variety of sources to data entities in the Blackboard platform.

Data EntitiesData that can be input to Blackboard Learn is grouped into the following eleven entities:

l User: Data consists of system role, ID, contact, and personal information.l Course: Data consists of Course Name, course section ID, and description information.l Organization: Data consists of Organization Name, organization section ID, and description

information.l Student: Data consists of the core information required to assign a Student to a given course section.l Staff Student: Data consists of the core information required to assign a staff member to a given

course section.l Organization Membership: Data consists of the core information required to establish a user’s

membership in a given organization.l Course Category: Data consists of the title, key, and availability information of a Course catalog

category.


9.1 S

P6 BETA D

RAFT


l Course Category Membership: Data consists of the information required to connect a Course to acategory.

l Organization Category: Data consists of the title, key, and availability information of anOrganization catalog category.

l Organization Category Membership: Data consists of the information required to connect anOrganization to a category.

l User Institution Role Membership: Data consists of the information required to connect a user withmultiple Institution Roles.

Course Data EntitiesThe following table details Blackboard Learn data entities that have a corresponding IMS data entity.





Organization Group A site for groups, organizations, clubs, and teams to have an online presence,share information, engage in increased communication, and collaborate on tasks.

Studentenrollment

Groupmembership





Groupmembership


User IDWhen updating the user ID of a Blackboard Learn user the file permissions that are applied to a course or groupmembership or role are not impacted by this change. When the user ID is changed, Web Folders links whichpointed to the user ID will have to be updated to use the new user ID information.

About the Data PackageThe classes in the data package (blackboard.admin.data) represent Blackboard Learn entities from thedatamodel. All entities, including Person, Course/Organization, Enrollment/Staff Student/OrganizationMembership, Course Category/Organization Category, and Course Category Membership/OrganizationCategory Membership, derive from the base class IAdminObject. All data classes are classes containing thefields defined in the datamodel as well as get/set methods for each.

Object ModelThe object model is based on the informationmodel in the IMS 1.01 Enterprise Specification. The IMSspecification provides five basic objects: Person, Course/Organization, Enrollment/Staff Student/Organization


9.1 S

P6 BETA D

RAFT


Membership, Course Category/Organization Category, and Course Category Membership/OrganizationCategory Membership.

Entity ClassesThe following classes exist within the Entity package. Each class can instantiate objects specific toBlackboard Learn.

l Person represents a user within the system.l Course / Organization are the base abstraction used to build Courses or Organizations. It is sub-

classed to provide additional semantics useful in integration. The provided subclasses are CourseandOrganization.

l Enrollment / Staff Student / Organization Membership are objects that represents theassociation of a Person with a Course or Organization. Course Category / Organization Categorydata consists of the title, key, and availability information of a catalog category.

l Course Category Membership / Organization Category Membership data consists of theinformation required to connect a Course or Organization to a category.

Incremental UpdatesThe entity objects support incremental updates. This means that if an entity that already exists in the systemneeds a single attribute to be updated, then the user of the API needs to only set the entity key and thatmodified attribute before calling the update() method. This allows a password to be changed without changingeverything else.

About Data Source Management and Data Source KeysDuring the planning processes, institutional business rules were identified as well as all the systems involvedwith storing institutional data that will be used in Blackboard Learn to create Courses, populate Courses,disable and delete records, and so on. This information is vital to deciding how to organize andmanipulate thedata within Blackboard Learn, database.

Separating data entities into different data sources is accomplished by creating and using Data Source Keys.Data Source Keys parse large amounts of data into smaller entities by tagging them with a unique identifier.This identifier ties pieces of data together to ensure that they are processed within the system according toinstitutional practices and identified business rules.

For example, an institution has Courses that are given in the fall semester, the spring semester and in thesummer. If all the Courses were kept in the same data set, everything time a change needed to take place,


9.1 S

P6 BETA D

RAFT


such as removing the fall Courses from the active course catalog, all the Courses would be affected becausethere is no way to differentiate the fall Courses from the spring or summer Courses even though they havedifferent attributes. By assigning Data Source Keys to each of the three time frames, Courses that areassigned to the fall can bemanipulated without affecting the spring or summer Courses.

About Data Source KeysData Source Keys are labels made up of alpha-numeric strings that allow different types of data from a singledata source to be grouped together so that they can be handled in a single operation. Snapshot processes databased on what Data Source Key it is associated with. Using Data Source Keys breaks up Snapshot processesinto separate operations to optimize system resources andmeet business rules.

Data Source Keys are created as needed and can be saved for future use. They can be used in almost infiniteways to categorize data, tying together data from different systems so it can be added to Blackboard Learn.Data Source Keys are stored in the Blackboard database and are referenced in the Snapshot properties file.

ExamplesHere is one example of how a data source key can be used:

ACME University teaches 1,000 Courses twice a year (Fall and Spring). Rather than lump all those classestogether, it would be easier to process them if they could be associated with two different Data Source Keysthat break them out by the semester in which they occur.

For instance, ACME assigns the FALL_Courses_05 Data Source Key to all fall Courses and the SPRING_COURSES_06 Data Source Key to all spring Courses. This makes processing themmuch easier by keepingthem separate. If these Courses were not identified with separate Data Source Keys then it would be difficult toadd, change, or remove all Fall Courses from the system without alsomodifying the Spring Courses as well.

Data Source Keys can be used inmany ways to categorize data but there are some general tips that should befollowed when creating and applying Data Source Keys to data.

l Keep a consistent naming convention for the Data Source Keys to prevent confusion when it is timetomodify or remove data.

l Avoid creatingmultiple Data Source Keys for entries that will remain for a long period of time (such asStudents or Faculty). Doing somay create unnecessary complications or problems.

l When archiving and removing Courses at the end of a semester it is best to disable them first for ashort period of time before archiving and removing them from the system. This will allow a shortperiod to confirm that they have been archived safely before removing them and help preventaccidental deletion of Courses that have not been safely preserved if desired.

Note: When assigning data sources to course andOrganization categories, child categories must belong tothe same data source as the parent category when the category tree is inserted. If child categories do notappear in the same data source as the parent, the child-parent relationship will not bemaintained.

About Data Source ManagementData SourceManagement (DSM) is a flexible method for identifying sets of data frommultiple external sourcesso that they can bemanaged within a single Blackboard Learn database. A data source is a logical set of data,sometimes simply associated with a source system, other times associated with type and term data as well.

All data that is pushed to the Blackboard Learn database is tagged with a data source identifier. Theseidentifiers, called Data Source Keys (DSK), are created using the Data SourceManagement Tool and are themeans by which certain data sets aremanaged. For example, an institutionmay choose to identify all Fall 2005records with the Data Source Key SIS.FALL2005 and all Spring 2006 records with the Data Source KeySIS.SPRING2006. Although the records all come from the same external data source, each of these identified


9.1 S

P6 BETA D

RAFT


data sets can bemanipulated separately within Blackboard Learn. In themost basic terms, a Data Source Keyis a value entered into the Blackboard database to "tie" users and Courses to a particular identifier.

About the DSM ToolDuring the planning processes, institutional business rules were identified as well as all the systems involvedwith storing institutional data that will be used in Blackboard Learn to create Courses, populate Courses,disable and delete records, and so on. This information is vital to deciding how to organize andmanipulate thedata within the Blackboard Learn database.

Separating data entities into different data sources is accomplished by creating and using Data Source Keys.Data Source Keys parse large amounts of data into smaller entities by tagging them with a unique identifier.This identifier ties pieces of data together to ensure that they are processed within the system according toinstitutional practices and identified business rules.

For example, an institution has Courses that are given in the fall semester, the spring semester and in thesummer. If all the Courses were kept in the same data set, everything time a change needed to take place,such as removing the fall Courses from the active course catalog, all the Courses would be affected becausethere is no way to differentiate the fall Courses from the spring or summer Courses even though they havedifferent attributes. By assigning Data Source Keys to each of the three time frames, Courses that areassigned to the fall can bemanipulated without affecting the spring or summer Courses.

The Data SourceManagement (DSM) tool is a command line application that creates andmanages DataSource Keys and associates them with their respective data entities. Once created by the DSM Tool, DataSource Keys are stored in the Blackboard database. Data Source Keys have nomeaning, but become anotherattribute of the data that they are associated with.

The DSM tool can be used with Snapshot and the Event Driven APIs.

The DSM tool is installed when Blackboard Learn is installed. The DSM tool is located in blackboard_home\apps\snapshot\bin\ in a typical installation.

DSM Tool Syntax and CommandsLocated in the blackboard\apps\snapshot\bin\ directory in a typical installation is a readme.txt filethat lists all the available commands for both the Data SourceManagement (DMS) tool and the Snapshot tool.The entire readme.txt file is located in Sample Properties File.

DSM Tool SyntaxCommands issued to the DSM Tool must follow a specific syntax in order to be processed correctly. Flags areused to specify arguments in a DSM Tool command.

DSM Tool Commands support the following flags:

l the “-f” flag and the invocation (command) that is to be runl the “-b” flag and the Data Source Key that is to be usedl the “-V” flag and the fully-qualified domain name of the virtual host / server name that will be usedl the “-d” flag and the description of the Data Source Key (the descriptionmust be enclosed with

quotes)*l the “-r” flag and the replacement Data Source Keyl the “-t” flag and the date*

Flags are case sensitive, so an upper case “V” needs to be used to denote the virtual host name, and the otherflags are in lower case.

Flags with an asterisk (*) are optional and can be omitted.


9.1 S

P6 BETA D

RAFT


Example: WindowsDSM –f [action] –b [data source key] –V [fully-qualified server name]

Example: Unix./dsm.sh –f [action] –b [data source key] –V [fully-qualified server name]

Taking the above criteria, a sample DSM command formatted in the correct syntax can be built like this:

DSM –f REMOVE –b Fall_COURSES_05 –V blackboardserver.acme.edu

Note: The DSM tool’s parameters are not operating system specific. The only difference is that Unix systemsuse the “./dsm.sh” invocation whileWindows systems use simply “dsm” or “dsm.cmd”.

DSM Tool CommandsTo create andmanage Data Source Keys, use the DSM Tool commands listed in the following table with theDSM Tool Syntax.

DSM Tool CommandDescription

LIST Lists all data sources.

CREATE To create a new data source.

REMOVE To remove a data source.

MODIFY To modify a data source. The modify command can be used to change the description, thekey, or both.

COUNTS_ALL To count all records for a data source. The count includes both enabled and disabledrecords.

COUNTS_DISABLED To list the count of disabled records for a data source.

COUNTS_ENABLED To list the count of enabled records for a data source.

DISABLE_ALL To disable all entities for a data source.

DISABLE_PERSON To disable all person (user) entities for a data source.

DISABLE_GROUP To disable all group (Course/Organization) entities for a data source.

DISABLE_MEMBERSHIP

To disable all membership (enrollment / staff Student) entities for a data source.

DISABLE_COURSE_CATEGORIES

To disable all course category entities for a data source. Note that all categorymemberships related to this category are not disabled in the database but are renderedunusable due to the disabled category.

DISABLE_ORGANIZATION_CATEGORIES

To disable all Organization category entities for a data source. Note that all categorymemberships related to this category are not disabled in the database but are renderedunusable due to the disabled category.

DISABLE_COURSE_CATEGORY_MEMBERSHIP

To disable all course category memberships for a data source.

DISABLE_ORGANIZATION_CATEGORY_MEMBERSHIP

To disable all Organization category memberships for a data source.

DISABLE_INSTITUTION_ROLE_MEMBERSHIP

To disable all Institution Role memberships for a datasource.


9.1 S

P6 BETA D

RAFT

Tools > Snapshot Tool

DSM Tool CommandDescription

PURGE_ALL To purge all entities for a data source. Purge only deletes disabled items.

PURGE_PERSON To purge all person (user) entities for a data source. Purge only deletes disabled items.

PURGE_GROUP To purge all group (Course/Organization) entities for a data source. Purge only deletesdisabled items.

PURGE_MEMBERSHIP To purge all membership (enrollment / staff Student) entities for a data source. Purge onlydeletes disabled items.

PURGE_COURSE_CATEGORIES

To purge all course category entities for a data source. This will also purge all categorymemberships related to the category. Purge only deletes disabled items.

PURGE_ORGANIZATION_CATEGORIES

To purge all Organization category entities for a data source. This will also purge allcategory memberships related to the category. Purge only deletes disabled items.

PURGE_COURSE_CATEGORY_MEMBERSHIP

To purge all course category memberships for a data source. Purge only deletes disableditems.

PURGE_ORGANIZATION_CATEGORY_MEMBERSHIP

To purge all Organization category memberships for a data source. Purge only deletesdisabled items.

PURGE_INSTITUTION_ROLE_MEMBERSHIP

To purge all Institution Role membership entities for a datasource. Purge only deletesdisabled items.

PURGE_SESSION To clear all persistent storage devices used by snapshot. Use this when snapshot andcopyinto operations are slow. This clears temp table data and cached data.

Snapshot Tool

Strategic PlanningImporting user, Course, enrollment, and staff data from an institution’s information systems into BlackboardLearn can involvemany different systems and different people. Blackboard Learn is installed with the tools toassist with this process, but every Organization is unique and has different requirements.

To establish a successful process, careful planning is necessary as well as an understanding of the underlyingsystems involved. The integration process is a collaborative effort between Blackboard Learn and theinstitution. Working together to design and then implement a seamless process takes considerable planning.Blackboard Consulting can provide the support, experience, and knowledge necessary to assist institutionswith an efficient integration.

Questions to Ask Prior to IntegrationInstitutions must answer the following questions prior to data integration:

l Which institutional systems contain the data for integration with Blackboard Learn?l How will attributes of the institutional systemmap to Blackboard Learn?l Which criteria must be satisfied before a data record can be sent from the institutional system to

Blackboard Learn?l How will integration provide the needed packaging and error handling practices required by the

institution?


9.1 S

P6 BETA D

RAFT


Project TeamsTo successfully plan and implement a data integration project, Blackboard recommends forming cross-functional teams representing each stakeholder in the project. These teams usually consist of:

l An institutional Project Managerl Analysts with detailed understanding of the institution’s business processes, needs, and associated

information systemsl Programmers with the ability to query, report from, and interface with the enterprise systems

If the institution is working with Blackboard Consulting on the data integration project, these teams should alsorepresent Blackboard, the institution, and solution partners. These teams may consist of:

l An institutional Project Managerl A Blackboard Project Managerl Institutional analysts with detailed understanding of the institution’s business processes, needs, and

associated information systemsl Institutional programmers with the ability to query, report from, and interface with the enterprise

systemsl Blackboard and solution-partner technical consultants

Steps to a Successful IntegrationThere are seven basic steps to a successful integration.

1. Define the scope and time frame of the data integration project: what data entities will beexchanged between the systems and when will the project be complete?

2. Develop, analyze, and document requirements, including ownership of data entities and attributes,key definition, attributemapping, datamodeling and trigger determination, timeliness, reliability,security, and operational issues.

3. Design, configure, and program a data-integration solution: although Blackboard Learn featuresmany built-in integration capabilities, some institutions may require additional customization.Where appropriate, the project team can use existing solutions from enterprise vendors, reuse priorsolutions developed for other institutions, or develop an entirely new custom solution.

4. Develop and document operating procedures for all affected parties.5. Test the system.6. Transfer the technology to the operations team at the institution.7. Train all relevant personnel.

Data Integration Planning ProcessDocument the planning, design, configuration and programming of the data integration process of steps two andthree in the previous list. The planning portion consists of developing the following:

l Data mapping: organize the data sources to prepare the data dictionary (a document that lists thevarious acceptable attributes for each data field) andmap required and optional attributes ofBlackboard Learn to those of institutional systems. The Blackboard Data Dictionary begins withCategory Data Feed Elements.

l Data lifecycle: generate business rules that regulate how data is handled, for example when recordsare added, removed or archived.


9.1 S

P6 BETA D

RAFT


l Data operations: generate rules that govern the use of the integration tools to transfer data, forexample how the system is initially populated, and how it is synchronized with other systems.

Tipsl Complete the data integration for one information system at a time; it is quicker to add a second

auxiliary system after the first is done.l When planning the integration, focus on getting the data into the system before determining when to

remove it. In most cases, institutions will have a whole semester or longer to complete the rules fordisabling data so the plan to remove it does not have to be completed up front.

l For assistance in planning data integration, please contact Blackboard Consulting.

Planning Frequency of Snapshot Data FeedsData can be loaded into the Blackboard Learn database on a schedule determined by the institution and definedby the institution’s business rules. The frequency of data feeds can change throughout the year for differentdata entities.

The following are some of the factors that need to be considered when determining the frequency of data feeds:

l Frequency of adding, modifying, and deleting data in institution systemsl Urgency of the data synchronizationl Institution system performancel Number of data entities to be fed from institution systems into a Course

SchedulingTo set the frequency, use the Task Scheduler withWindows 2003 orWindows 2000 operating systems and thecron commandwith Linux® or Solaris® operating systems. In addition, Windows users may also use the atScheduler or the at command from the command prompt.

Note: Frequency can also be controlled with the Snapshot Controller, a custom built utility used to automateprocessing of one or more Snapshot commands. The Snapshot Controller may be built by the institution orprovided through Blackboard Consulting. To learnmore about automating Snapshot, see About Snapshot Automation.

Planning Through StandardizationFor systems to be able to exchange data, standardized structures need to be in place. The informationmodelused by Blackboard Learn is that defined by the Instructional Management System (IMS) consortium. IMS is aglobal effort whose primary objective is to define a standardized set of structures that can be used to exchangedata between different instruction-based systems. IMS has defined an informationmodel and provided aspecification for transfer of such data.

To learnmore, visit the IMSWeb site: http://www.imsproject.org/.

Standardized StructuresThe structures within Blackboard Learn that are standardized to use the IMS model for exchanging data allowfor the successful mapping of an institution’s data into Blackboard Learn. The following table details thesestructures.


9.1 S

P6 BETA D

RAFT

http://www.imsproject.org/






Organization Group A site for groups, Organizations, clubs, and teams to have an online presence,share information, engage in increased communication, and collaborate on tasks.

Studentenrollment

Groupmembership





Groupmembership


Snapshot Use CasesSnapshot can be used to update the Blackboard database inmany ways based on an institution’s businessrules. The following sections contain use cases with a brief description of the process used to execute them.

ExamplesNote: In the following use cases, “webserver host” indicates that users should insert the name of theirwebserver host, for example blackboard.school.edu.

Use Case 1Organize Students in the Information Systems Management program into two groups; Project Management(PM) and ISD (Information System Development).

1. Create two Data Source Keys: IFSM.PM.02 and IFSM.ISD.02.2. Associate the Data Source Key to the selected user group in the snapshot.properties file.

Insert the users with the desired Snapshot command:

Controls whether to copy user grades during COPYINTO operations. This will also copy enrollments.The available options are Y/N.

groups.copy=Y

Designates flag to enablemembership data copying for configuration property filemembership.copy=Y.

Windows

C:\blackboard\apps\snapshot\bin>snapshot –V "webserver host" -f usr_snpsht –t..\Demo\users\ISD.02.csv -C

..\data\snpshot.properties

UNIX

/usr/local/blackboard/apps/snapshot/bin >./snapshot.sh –V "webserver host" -fusr_snpsht –t ../Demo/users/ISD.02.csv -C


9.1 S

P6 BETA D

RAFT


../data/snpshot.properties

3. Run the same process again using Snapshot commandwith the file PM.02.csv associated with thekey IFSM.PM.02.

Use Case 2A Student is disabled in the system until their financial aid arrives. Disabling a record rather then deleting it isoften the best option if the record will be activated at a later time. When a user is disabled the user record existswithin the database but is not active in Blackboard Learn. The user cannot login. However, the user recordappears in the System Control Panel in gray text with an icon that signals its disabled status.

A Student can be disabled by changing an element in the Student record and running the Snapshot commandagain using the same source key.

Use Case 3Organize a Statistics Course so that it is offered in two sections over the Summer 2006 semester.

1. Create Data Source Keys for the Course with two sections, offered in a Summer 2006 semester:

Windows

C:\blackboard\apps\snapshot\bin\dsm –V"webserver host"–f create –bstats.101.SUM.10 –d Statistics 101 – section 10 summer 2002"

C:\blackboard\apps\snapshot\bin\dsm –V "webserver host" –f create –bstats.101.SUM.11 –d "Statistics 101 – section 11 summer 2002"

UNIX

/usr/local/blackboard/apps/snapshot/bin/dsm.sh –V "webserver host" –f create –bstats.101.SUM.10 –d "Statistics 101 – section 10 summer 2002"

/usr/local/blackboard/apps/snapshot/bin/dsm.sh –V "webserver host" –f create –bstats.101.SUM.11 –d "Statistics 101 – section 11 summer 2002"

2. Set the properties to the desired key each time a Course is inserted.3. Insert the first and second sections of the Statistics course:

Windows

C:\blackboard\apps\snapshot\bin>snapshot –V "webserver host" -f crs_snpsht =t..\demo\course\stat_sun_02_10.csv –C ..\data\snapshot.properties

C:\blackboard\apps\snapshot\bin>snapshot –V "webserver host" -f crs_snpsht =t..\demo\courses\stat_sun_02_11.csv –C ..\data\snapshot.properties

UNIX

/usr/local/blackboard/apps/snapshot/bin >./snapshot.sh –V "webserver host" -fcrs_snpsht =t ../demo/courses/stat_sun_02_10.csv –C ../data/snapshot.properties

/usr/local/blackboard/apps/snapshot/bin >./snapshot.sh –V "webserver host" -fcrs_snpsht =t ../demo/courses/stat_sun_02_11.csv –C ../data/snapshot.properties

Use Case 4Enroll Students in a Course. The file used to enroll Students into a Course uses the same idea as a relationaldatabase. The file to enroll users is created by combining external_person_key and external_course_key.

1. Create a Data Source Key for the course enrollment:

Windows


9.1 S

P6 BETA D

RAFT


C:\blackboard\apps\snapshot\bin>dsm –V "webserver host" –f create –benr.stat.10.sum –d ">enrollment for Statistics 101 section 10 for summer of2002 semester"

UNIX

/usr/local/blackboard/apps/snapshot/bin/dsm.sh –V "webserver host" –f create –benr.stat.10.sum –d "enrollment for Statistics 101 section 10 for summer of 2002semester"

2. Set this key in the snapshot.properties file before running the Snapshot command.3. Enroll selected Students into the course.

About the Snapshot ToolThe Snapshot Tool is a simple command line program that takes a feed file and pushes the data into theBlackboard Learn database. It is built for bulk operations and has several modes that can be used to facilitatedifferent workflows. The Snapshot Tool is automatically installed as part of Blackboard Learn. It can also beinstalled on a separate computer whichmay be necessary for clients using Blackboard ASP, or for certainnetwork setups.

Snapshot allows all data for an entity to be transferred from an institutional information system to theBlackboard database at a particular point in time. It is called a “snapshot” because it is akin to taking a picture ofthe institutional database at that point in time and transferring the contents to Blackboard Learn.

The Snapshot Tool can also associate Learning Levels (Standards) to Courses by using a downloaded LearningLevels CSV (comma separated values) file. The keys in this file are used to associate courses to appropriateLearning Levels at the time the course is created, or in any coursemodification process executed using theSnapshot Tool. The Learning Levels file includes the document identification, the name of the learning level, thename of the standard set the learning level is a part of, the type of standard, and the status of the standard asset by the administrator. To learnmore about using CSV files with the Snapshot Tool, see Syntax for theSnapshot Tool.

To populate a Blackboard Learn installation, operations at small institutions and in testing environments, thesnapshot tool can be usedmanually. However, as the Blackboard installation grows, keeping up with dataintegrationmanually can rapidly become overwhelming.

Because every institution is different, the ways that Snapshot can be automated can vary widely, depending onthe business rules and the other systems involved. To achieve specific goals, Blackboard recommends aservices engagement with Blackboard Consulting.

About the Snapshot Tool WorkflowTo push institutional data into Blackboard Learn, Snapshot follows a certain workflow, relying on different typesof files that are processed together during a system update. The process diagram illustrates the work flow.


9.1 S

P6 BETA D

RAFT


Snapshot Process Workflow

The Snapshot Tool was used to create Data Source Keys to associate certain types of information together intothe same data source so that it can be processed in one batch. This Data Source Key is added into theProperties File. The Properties File also contains other information necessary to interpret and parse datacorrectly.

The data in the Feed File has been extracted from an intuitional database and formatted so that it is compatiblewith the Blackboard database. The Feed File has a header row at the top explaining the types of informationcontained in the file and individual rows (or one row) containing the data to bemodified, divided into columns bya delimiter character.

Data Life Cycle PlanningData life cycle planning defines the rules that control how the Institutionmanages data. These rules willdetermine what data is transferred to Blackboard Learn, when it is transferred, as well as any other conditionsfor data handling.


9.1 S

P6 BETA D

RAFT


Data Life Cycle PlanningData life cycle planning involves the creation of business rules. Business rules are statements that define orconstrain some aspect of the business. They assert structure to control or influence the behavior of thebusiness. The business rules set by an Institution will control whether or not datamay be created or changed,when data can be sent, and the implications when this occurs.

Important Business RulesSome important business rules to consider are:

l Where data is stored?l What business processes impact the data?l Which records to send?l How often to send records?l When to stop sending specific records?l When to archive CourseWeb site andOrganizationWeb site records?

Documenting the business rules of an institution will provide the foundation for what data is integrated by whichmethods over time. Once documented, these rules can be applied to the systems involved ensuring that datafrom each institutional system is integrated into Blackboard Learn exactly as intended.

Data StatesAll records within the system exist in one of three states -- active, disabled, or deleted. The status of that stateis changed based on the life cycle of the data in the system. A record with a status of active can be disabled ordeleted. A disabled record can be activated or deleted. The specific methods for changing the state of the dataare discussed inmore detail in the parts of this project.

Disabling active objects and enabling inactive objects is done through the Snapshot Tool or Event-Driven API.Deleting a record can be accomplished through the integration tools or through the System Control Panel userinterface. Course andOrganization Content are the only data entities that can be archived before being deleted.Archived data can be downloaded from and restored into the Blackboard Learn platform through the userinterface or using batch tools.

In addition to the state, most record types have an additional property called “availability” which directlycorrelates to the record's usage. The availability property can be controlled through the integration tools(Snapshot or Event-Driven) and can also be altered through the Control Panel GUI interfaces.

Behavior of Data Records in Relation to Their StateThe following table details each entity and a description of its records’ behavior in certain states withinBlackboard Learn.

Entity StateBehavior inBlackboard Learn

User Active Default state. The userrecord appears in thesystem.


9.1 S

P6 BETA D

RAFT



Disabled The user record exists within the database but is not activewithin the system. The user cannot login, however the userrecord appears in the System Control Panel in gray text with anicon that signals its disabled status.

Deleted Deletes user data and Course and organization membership.

Course or Organization Active Default state. TheCourse appearswithin BlackboardLearn.

Disabled The Course does not appear to any users within BlackboardLearn user interface; however it still exists in the database. Therecord appears in the System Control Panel in gray text with anicon that signals its disabled status.

Deleted Deletes all Course content, enrollments, and all activity dataassociated with the Course.

Student Enrollment orOrganizationMembership StudentEnrollment orOrganizationMembership

Active Default state. Theenrollment appearswithin BlackboardLearn.

Disabled The Student enrollment record is in the database but cannot beviewed through the user interface except by the Administrator.The record appears in the System Control Panel in gray text witha circle icon with a line through it to signal it is disabled.

Deleted The enrollment record is deleted from Blackboard Learn and allactivity associated with the enrollment with the exception ofDiscussion Board messages.

Staff Student Active Default state. TheStudent appearswithin BlackboardLearn.

Disabled The Student record appears in the database but not in the userinterface. The Instructor or staff member may not access theCourse.

Deleted The record is deleted from Blackboard Learn.

Course or OrganizationCategory

Active Default state. Thecategory appearswithin BlackboardLearn.

Disabled The category exists in the database but does not appear inBlackboard Learn. Courses listed under the category are notdeleted.

Deleted The category does not exist in Blackboard Learn.

Course or OrganizationCategory Membership

Active Default state. The linkappears withinBlackboard Learn.


9.1 S

P6 BETA D

RAFT



Disabled The link exists in the database but does not appear inBlackboard Learn.

Deleted The link does not exist in Blackboard Learn.

User Institution RoleMembership

Active Default state. The useris able to access theappropriate privilegesof the Institution Role.

Disabled The link exists in the database the user does not have theprivileges of the Institution Role.

Deleted The link does not exist in Blackboard Learn.

Behavior of Records in Active StateThe following table details the behavior of active entities within Blackboard Learn based on availability.

Entity AvailabilityBehavior in BlackboardLearn

User Available Default. Can accessfeatures and functions ofBlackboard as definedby roles.

Unavailable User cannot log in to the system. Instructors can see the record incourse and organization interfaces. The User Name appears as gray inthe user interface with a circle icon with a line through it that signals it isunavailable.

Course orOrganization

Available Default. Can beaccessed by allauthorized users.

Unavailable Only administrators and course staff can view and access the course.Does not affect enrollments and staff Students.

StudentEnrollment orOrganizationMembership

Available Default. Enables usersto access their Coursesor organizations.

Unavailable Instructors and administrators can see the unavailable Studentenrollment within the course/organization membership list. The recordappears as gray on the user interface.

Staff Student Available Default. Enables staff toaccess their Coursesand organizations.

Unavailable Staff and administrators can see the unavailable Student within thecourse membership list. The record appears in gray and the course isinaccessible to the staff member.

The Data Life Cycle and Triggering EventsTo plan for the successful transfer of data from institutional systems into Blackboard Learn, the life cycle ofdata has to be taken into consideration. The data life cycle is the series of events that control the actions of a


9.1 S

P6 BETA D

RAFT


record from its creation to when it is deleted. A data record in the Blackboard platform has a life cycle ofusefulness and an associated status that it can pass through as its usefulness changes. The systemprocesses the data differently based on its state in the life cycle.

After creation, data can exist in two states within Blackboard Learn; it can be active (enabled) or it can bedisabled. Disabling a record rather than deleting it is often the best option if the record will be activated at a latertime. For example, a Student record can be disabled for a semester if that Student is not taking any onlineCourses, but may do so in the future. Deleting a record removes it from Blackboard Learn altogether, and if theStudent in the example were deleted, the record would have to be recreated and added back into Blackboard ifthat Student decided to take another online Course the following year.

All data entities are disabled using data integration tools. Course andOrganizations are the only data entitiesthat may be disabled through the user interface. They can be introduced into the system at a later date throughthe same user interface.

Triggering EventsA triggering event is an event that impacts (adds to, updates, or deletes) data within the Blackboard platform.When planning data integration, written definitions of triggering events and complete documentation of thecriteria for adding, updating, disabling, or deleting data will increase the long-term integrity of the system andpromote organizational consistency.

For example, an institution can define a triggering event as a Student adding or dropping a Course within adefined timeframe. If the Student adds a Course within the defined timeframe, the system can trigger an eventto add that Student record to the course. If a Student drops a Course within the defined timeframe, the systemcan trigger an event to disable that Student record for the course. If the Student drops a Course outside of thedefined timeframe, the system will not trigger an event and the Student record will not be disabled.

Data LifecycleEach data record has a lifecycle. A data life cycle is the creation, update, and archiving or deletion of a recordover time.


9.1 S

P6 BETA D

RAFT


Data Operations PlanningData Operations planning involves choosing the data integration tool or tools that best suits the needs of theInstitution and applying the business rules developed during the data lifecycle planning.

Importing Data into the Blackboard Learn DatabaseBlackboard Learn imports administrative data using a data feed, which can be done using a flat file, an XML file,or the Event Driven API (Application Program Interface). A data feed request can be:

l Add a new recordl Update an existing recordl Delete an existing recordl Change the key of a record

WARNING! Take care when changing the key of a record. Changing the key or unique identifier of arecord should be done sparingly and with the greatest care. However, there are some situations where it isnecessary. For example, if a Social Security number is used as the key for user records. Foreign Studentsare assigned a temporary Social Security number, when they enroll this will be used as the key. When aforeign Student receives a permanent Social Security number, it makes sense to change the key within thesystem.


9.1 S

P6 BETA D

RAFT


Methods of IntegrationThere are two basic methods of data integration; using Snapshot and the Event Driven APIs. The twomethodscan be combined into a composite method, configured according to Institution specifications, that uses thestrengths of eachmethod while off-setting eachmethod’s limitations.

Snapshot-based ApproachSnapshot allows all data for an entity to be transferred from an institutional information system to theBlackboard Learn database at a particular point in time. It is called a snapshot because it is akin to taking apicture of the institutional database at that point in time and transferring the contents to Blackboard Learndatabase.

In a snapshot-based approach, snapshots are taken at pre-determined times by the Snapshot Generator. TheSnapshot Generator then creates a snapshot file from the relevant information and the Snapshot Tool transfersthat file to Blackboard Learn database.

Note: The Snapshot Generator is a utility specifically written to take data from the institutional informationsystem, format it, and input it into the Snapshot process. The Snapshot Generator must be created andcustomized before it will function correctly.

The Snapshot-based approach offers higher failure tolerance than the Data Integration approach, but reducessynchronization because reports of relevant data (“snapshots”) are run at regularly scheduled times, forexample once a day, not dynamically. Snapshot is best used to handle large batches of data. For example, theinitial population of Blackboard Learn database is easily accomplished using the Snapshot-based solution.

The Snapshot Tool sends commands to the Blackboard Learn database instructing it to update any data thathas changed since the last comparison. In the event of a Blackboard Learn database failure, Administrators canrun another snapshot or process the last snapshot. Because the entire data set must be compared each timethe Snapshot Tool is run, this approach’s performance is slower than the Event-Driven Integration approach.Dividing snapshots into logical subsets, using Data Source Keys, can alleviate some of the problemsassociated with a bulky Snapshot process.

Data sources allow for:

l Smaller filesl Faster processingl Different update patterns

To learnmore about identifying groups of data and constructing data sets and Data Source Keys, see AboutData Entities.

When the Snapshot Tool is used in high-demand environments where certain information in Blackboard Learnmust be routinely updated on a day-to-day basis, the ability to use Snapshot manually or with basic scriptingmay become too tedious or difficult to manage efficiently and effectively. In these circumstances, Blackboardcan assist in the creation of custom scripted Snapshot routines that integrate Blackboard with a StudentInformation System or build this integration from scratch with integration assistance from your technical staff.For a high level overview, see About Snapshot Automation. For more detailed information, contact BlackboardConsulting.

Event Driven APIs approachThe Event Driven APIs allow institutional systems and Blackboard Learn database to exchange eventinformation in real time. When an event occurs (add, update, or delete) that changes the state of the data in theInstitution systems, a transaction is sent to Blackboard Learn database to provide synchronization between thetwo systems dynamically.


9.1 S

P6 BETA D

RAFT


Under the Event-Driven approach, when a triggering event takes place, a command is automatically sent toBlackboard Learn database. Blackboard Learn database receives the command, executes it, and returns astatus update to the information system. If a failure occurs, the command is saved or the event is “marked” untila backup takes place and the command can be re-sent successfully. To implement this approach, access totriggers in the enterprise system is required.

Combined Snapshot/ Event Driven API approachThe combined approach attempts to use the best aspects of bothmethods. First, the Snapshot approach isused to achieve improved failure tolerance at the expense of performance. Then, the important events thatrequire quick synchronization with Blackboard Learn database are handled using the Event Driven APIapproach. Using this approach, an Institution can reduce the complexity of managing failures while maintaininga high level of synchronization. It can be implemented for all triggering events or just themost significant.

Using Snapshot ModesDepending on the operation specified in the command line processed by Snapshot, the records specified in theFeed File will be affected differently. The four primary modes of snapshot are:

l Snapshot Model Manual Model RemoveModel Course Copy (COPYINTO)

Snapshot ModeThe Snapshot mode processes a Snapshot against all records in the database for the specified data sourcekey. Records are processed in the following ways:

l If the record is in the Feed File, but not in the Blackboard Learn database, an insert is performed andthe record is added.

l If the record is in the Feed File and in the Blackboard database, an update is performed to BlackboardLearn database.

l If the record is not in the Feed File, but in the Blackboard database, the record is disabled. If a laterSnapshot contains a record in the disabled state, the record is enabled and updated. The entity mayonly be re-enabled by including it in a subsequent Snapshot file, not through the Blackboard userinterface. To learnmore see the topic, Data Lifecycle.

Note: Because all entities within a given data source are disabled if not included in a feed file, it is important todouble-check the contents of the file before running in snapshot mode. An improper feed file could result inlarge amounts of data being disabled. For small updates and testing, usemanual mode instead.

Manual ModeIn manual mode, only the specific records in the feed file are processed. Other records in the datasource keyare not affected. Records are processed in the following ways:

l If the record is in the Feed File, but not in the Blackboard database, an insert is performed and therecord is added.

l If the record is in the Feed File and in the Blackboard database, an update is performed to BlackboardLearn database.

l If the record is not in the Feed File, but in the Blackboard database, the database record is not altered.


9.1 S

P6 BETA D

RAFT


Becausemanual mode does not affect records not listed in the feed file, users may usemanual modeto add a small number of records without worrying about the possibility of disabling records.

Remove ModeRemovemode is used to remove Courses, enrollments, staff Students, and so on. LikeManual mode it onlyprocesses those records contained in the Feed File. Data is purged for each record identified in the Feed File.This is a permanent delete. The record is permanently removed from the database, including any associationsof the record (that is, if the user record is removed, any enrollments and files associated with the user arepermanently deleted. If a Course is removed, any enrollments associated with the course are also deleted).

Course Copy Mode (COPYINTO)Course Copy mode, called “COPYINTO," allows automatic management of course andOrganization Content.The commands can be used to add content from Course Templates tomany different Courses or organizations.The COPYINTO command can be issued as part of a Snapshot or Manual operation, or as a stand-aloneoperation by invoking the CRS_COPYINTO or ORG_COPYINTO command.

To perform a Snapshot or Manual operation using COPYINTO, use CRS_SNPSHT or CRS_MANUAL with the –toption using the TEMPLATE_COURSE_KEY field in the feed file. To copy both content, and links use "-atrue"; by default the setting is "-a false" whichmeans if the -a option is omitted then the links will not becopied.

Using the COPYINTO in this way is only meant for populating new Courses. Using this method with existingCourses will not copy the data. To use COPYINTOwith existing Courses, use CRS_COPYINTO instead

Note: In instances where a copy occurs on update, if the information from the source has already been addedto the destination course, it may be added again resulting in duplicate data. See the description for the"reconcile" snapshot properties option.

COPYINTO operations use the Template_Course_Key or Template_Organization_Key to specify thesource of the copy operation. Depending on the ownership setting for Template_Course_Key orTemplate_Organization_Key, the COPYINTO operation will process the information according to thefollowing table.

Operation Ownership of Template Key Result

COPYINTO update Blackboard Copy

not Blackboard Copy

COPYINTO insert Blackboard Copy

not Blackboard Copy

Snapshot update Blackboard No Copy

not Blackboard Copy

Snapshot insert Blackboard Copy

not Blackboard Copy

Manual update Blackboard No Copy

not Blackboard Copy

Manual insert Blackboard Copy

not Blackboard Copy


9.1 S

P6 BETA D

RAFT


Update LogicWhen a record is updated, ownership of the data fields, if applicable, is processed so that data owned byBlackboard Learn is not changed. Null values in a data field are ignored and the data is not changed. Therefore,a field is only updated if it is non-blank and not owned by Blackboard Learn. To clear a field (for example toremove amiddle name), set it to a single space character.

Setting Up the Snapshot Tool ServiceThe configuration properties, stored in configuration files, determine the Snapshot Tool operating parameters. Itis common to all invocations of the Snapshot Tool. Under most conditions it is not necessary tomake changesto the properties files as the values are set at installation.

Configuration Properties FilesThe configuration properties files are stored in the /blackboard/config directory (blackboard\configforWindows users). With Snapshot and the Event Driven APIs, the following properties files are used:

service-config-snapshot-soap.properties

service-config-snapshot-jdbc.properties

These files are configured at install. If a change needs to bemade, backup these files and use them astemplates for new config files that include the desired properties.

The following table describes the parameters that can be adjusted.

Parameter Values

blackboard.service.log.param.logdef.default.verbosity DebugInformationWarningErrorFatal

blackboard.service.log.param.logdef.default.copyToConsole True or False

To learnmore and additional parameters for property files can, see Using the Properties File.

Note: All properties files are formatted similar toWindows.ini files, with name/value pairs. Comment linesbegin with a hashmark (#).

Invoke Property File for Data IntegrationIt is necessary to invoke a properties file when running the Event Driven APIs from a client machine. The filethat should be invoked is:

service-config-snapshot-soap.properties

Database Configuration FileThe following two files must be changed if the Administrator changes the bbadmin password:

/blackboard/config/bb-datastores.xml

/blackboard/config/bb-datastores-standalone.xml


9.1 S

P6 BETA D

RAFT


Initialize Persistence with SOAPSimple Object Access Protocol (SOAP) is a set of conventions used for invoking code using XML over HTTP.When programming using the Event Driven APIs, the SOAP password (MD5 encrypted) must be passed whenrun from a client. For example:

System.getProperties().setProperty(CIConstants.REMOTE_PASSWORD,"password");

java "-Dremote.access.password=password"

Using the Properties FileThe Properties File is referenced in the Snapshot command to ensure that the data contained in the Feed File isinterpreted correctly when operated on in the Blackboard Learn database.

Existing Properties FileBlackboard Learn is installed with a Properties File, located in Snapshot directory and namedsnapshot.properties. This file may be copied, modified and saved under a different name. It is notuncommon to have several different Properties Files for different batch jobs.

How to Edit the Properties FileThe Properties File consists of properties and their associated values separated by an “=” (equals) sign. Eachproperty is on its own line. Comments are tagged by the “#” (pound or hash) sign. For example, the property thatdefines the delimiter for the Feed File would appear as:

# delimeter used for parsing snapshot filesdata.delimeter=|

If the institutional data feed file has been formatted with a different delimiter character, for example a “,”(comma), the Properties File would have to bemodified tomatch in order to ensure the Feed File data wasparsed correctly.

# delimeter used for parsing snapshot filesdata.delimeter=,

The following table lists all the properties that can exist in a Properties File and their associated values:


announcements.copy Flag that enables copying of announcements for COPYINTO operations. “Y”or “N” If this is set to “N”, announcements that appear in a source course orOrganization will not be copied into the destination course. Default value is“Y”.

assessment.copy Flag that enables copying of assessments for COPYINTO operations. “Y” or“N” If this is set to “N”, assessments that appear in a source course orOrganization will not be copied into the destination course. Default value is“Y”.

availability.rule.copy Flag that enables copying copy adaptive release rules in the course. If set toyes, a COPYINTO operation will copy adaptive release rules that only dependon other copied items.” Y” or “N” Default value is “Y”.

calendar.copy Flag that enables copying of calendar items for COPYINTO operations. “Y” or“N” If this is set to “N”, calendar items that appear in a source course orOrganization will not be copied into the destination course. Default value is“Y”.


9.1 S

P6 BETA D

RAFT



cartridge.copy Flag that enables copying content, assessments, and discussion boards thatcame from a cartridge. ” Y” or “N” Default value is “Y”.

categories.copy Flag that enables copying of course or Organization Categories forCOPYINTO operations. “Y” or “N” If this is set to “N”, category membershipassociated with a source course or Organization will not be copied into thedestination course. Default value is “Y”.

chat.archive.copy Flag that enables copying of chat archives for COPYINTO operations. “Y” or“N” If this is set to “N”, chat archives that appear in a source course orOrganization will not be copied into the destination course. Default value is“Y”.

chat.session.copy Flag that enables copying of chat sessions for COPYINTO operations. “Y” or“N” If this is set to “N”, sessions that appear in a source course or Organizationwill not be copied into the destination course. Default value is “Y”.

course.content.copy Flag that enables copying of course content for COPYINTO operations. “Y” or“N” If this is set to “N”, course content that appears in a source course orOrganization will not be copied into the destination course. Default value is“Y”.

course.settings.copy Flag that enables copying of various settings for COPYINTO operations. “Y” or“N” If this is set to “N”, settings from a source course or Organization will notbe copied into the destination course, and the destination course will usesystem default settings. Default value is “Y”.

course.statistics.copy Flag that enables copying Course Statistics. "Y" or "N" Default value is "Y".

data.delimiter The column delimiter for the input file. This field is ignored for XML-basedfeeds. Setting the data delimiter allows for other delimiters to appear in thedata. For example, if a comma is used in the data, select another delimiter toprevent errors. By default, the delimiter is a pipe “|”, which is recommendedsince it is unlikely to appear in most data.

data.source.key Data source key to be used for the snapshot operation (see Part 2, Datasource management, for an overview of datasource keys). The specified datasource must first be defined with the DSM Utility before a snapshot or updateis run with this key. This property is required and can be overridden from thecommand line.

discussion.board.archive.copy Flag that enables copying of Discussion Board archives for COPYINTOoperations. “Y” or “N” If this is set to “N”, archives that appear in a sourcecourse or Organization will not be copied into the destination course. Defaultvalue is “Y”.

discussion.board.copy Flag that enables copying of Discussion Boards for COPYINTO operations.“Y” or “N” If this is set to “N”, discussion boards that appear in a source courseor Organization will not be copied into the destination course. Default value is“Y”.

drop.box.copy Flag that enables copying of drop box items for COPYINTO operations. “Y” or“N” If this is set to “N”, drop box items that appear in a source course orOrganization will not be copied into the destination course. Default value is“Y”.


9.1 S

P6 BETA D

RAFT



encrypt.card.number Flag enabling the system to accept encrypted card numbers (for use withcommunity engagement). "N" signifies that the card number is not encrypted."Y" signifies that the card number is already encrypted. Card numbers areunencrypted using a key shared between the Blackboard Transaction Systemand the Blackboard Learn. If the card number is not encrypted at import, it willbe encrypted by the Blackboard Learn using the shared key. Therefore, it isvery important that this flag is set correctly, otherwise, card numbers will beprocessed incorrectly.

encrypt.password Flag enabling automatic MD5 encryption of passwords provided. “Y” or “N”.The default is “Y”, meaning that the passwords should be provided inplaintext, and the system will automatically encrypt them to the MD5 formatused in the database. If the passwords are already being supplied in MD5format, set this to “N”.

entity.bb.controlled.fields Attributes that are owned by the Blackboard Learn database. That is, theyshould not be overwritten by the manual update or snapshot. On insert, theinitial value in the feed will be entered into the database. However, on update,the value will not be changed. This is an effective way of updating userinformation without overwriting user passwords, fax numbers, or other similarinformation. Entity (as is a variable in the property) is one of person, group,membership, category, or category membership. The value of this property isa comma-delimited list of columns (attributes).

error.delimiter String used to mark the beginning of an error in the error log file. Default valueis (!).

escape.character Character to be used in escaping the delimiter in use. The default is “/”. Forexample, if the delimiter is pipe “|” and the escape character is “/”, then thesequence “/|” will indicate a literal pipe character.

glossary.copy Flag that enables copying the glossary. ” Y” or “N” Default value is “Y”.

gradebook.copy Flag that enables copying of gradebook content for COPYINTO operations.“Y” or “N” If this is set to “N”, gradebook content that appears in a sourceCourse or Organization will not be copied into the destination Course. Defaultvalue is “Y”.

grades.copy Flag that enables copying the grades in the Course. ” Y” or “N” Default valueis “Y”.

groups.copy Flag that enables copying of Course Group content for COPYINTOoperations. “Y” or “N” If this is set to “N”, Course group content that appears ina source Course or Organization will not be copied into the destinationcourse. Default value is “Y”.

header.validation Flag enabling validation of header information. Determines if labels providedin the first line of the feed file are supported for the current operation. “Y” or“N”

log.stdout Flag to indicate the display of status information to the system console. “Y” or“N” The default value is “N”.

max.error.count Maximum number of errors allowed before processing of the current fileterminates. Records that have been successfully processed are not rolledback. A setting of “-1” will allow an infinite number of errors during processing.A setting of “0” will terminate the process at the first error.

membership.copy Flag that enables copying of membership information for COPYINTOoperations. “Y” or “N” If this is set to “N”, Student enrollments and staffStudents that appear in a source Course or Organization will not be copiedinto the destination Course. Default value is “Y”.


9.1 S

P6 BETA D

RAFT



membership.datasource.key The datasource key to be assigned to enrollments of a Course that is createdthrough Course Copy. If no datasource key is identified, the enrollments willuse the same datasource key as the source. This parameter is only usedwhen “membership.copy” is set to “Y”.

membership.exact.copy Flag that enables copying private membership data. ” Y” or “N” Default valueis “Y”.

parse.allow.default Enables the administrator to allow incorrect data in the snapshot feed to bereset to the default. “Y” or “N”. Default is “N”

reconcile Flag that, when set to “Y”, enables a Course Copy operation to completelyreplace the settings and Course Menu of the destination Course. This workseven when copying into a new Course (removes the default settings anddefault Course Menu and replaces it with the source Course). When the flagis set to “N” the destination Course will contain Course Menu items from boththe original destination Course and the source Course. Note that setting thisto "Y" can result in the loss of data in the destination Course.

snapshot.batch.size Flag designating the number of records handled in a database transaction.Default is set to 300.

staff.information.copy Flag that enables copying of staff information for COPYINTO operations. "Y" or"N" If this is set to "N", staff infromation that appears in a source Course orOrganization will not be copied into the destination Course. Default value is"Y".

suppress.clone.events Flag that will suppress CLONE events. If set to yes, CLONE events will besuppressed. ” Y” or “N” Default value is “Y”.

tasks.copy Flag that enables copying of tasks for COPYINTO operations. “Y” or “N” If thisis set to “N”, tasks that appear in a source Course or Organization will not becopied into the destination Course. Default value is “Y”.

wait.length Used to configure pause between persistence actions. (seconds) The defaultvalue is”-1” indicating no waiting This value can be set to improve databaseperformance (reducing the impact of the Snapshot operation on the system),at the expense of total execution time..

Dependenciesl If membership.exact.copy is set to Y, then membership.copy will be forced to Y. Data

dependent on enrollments can only be copied if the enrollment data itself is being copied.l If grades.copy is set to Y, then membership.exact.copy will be forced to Y. Data dependent

on enrollments can only be copied if the enrollment data itself is being copied.

Syntax for the Snapshot ToolCommands issued to the Snapshot Tool must follow a specific syntax to be processed correctly. Flags areused to specify arguments in a Snapshot Tool command line. The snapshot tool is located in theblackboard\apps\snapshot\bin directory.

Snapshot Tool FlagsSnapshot commands consist of the following components:

l the “-f” flag and the invocation (command) that is to be runl the “-t” flag and the full path location to the Feed File


9.1 S

P6 BETA D

RAFT


l the “-C” flag and the full path location to the Properties Filel the “-V” flag and the fully-qualified domain name of the virtual host that will be used

Flags are case sensitive, so an upper case “C” needs to be used to denote the full path name to the PropertiesFile and an upper case “V” needs to be used to denote the virtual host name. The “f” and “t” flags are in lowercase.

ExampleThe syntax for an entire Snapshot commandwill look something like the following.

WindowsSnapshot –f [action] –t [x:\location of feed file] –C [x:\location of properties file] –V[fully-qualified server name])

UNIX./snapshot –f [action] –t [/location of feed file] –C [/location of properties file] –V[fully-qualified server name])

Taking the above criteria, a sampleWindows syntax can be built like this:

Snapshot –f CRS_MANUAL –t c:\snapshotstuff\feedfiles\fallCourses.txt –Cc:\snapshotstuff\snapshot.properties –V blackboardserver.acme.edu

Taking the above criteria, a sample Unix syntax can be built like this:

./snapshot.sh –f CRS_MANUAL –t /snapshotstuff/feedfiles/fallCourses.txt –C/snapshotstuff/snapshot.properties –V blackboardserver.acme.edu

Using Operational Commands for Snapshot ModesOperational commands for Snapshot determine themode Snapshot will run in and how Snapshot will processthe data in the Feed File. Snapshot commands are issued using a specific syntax that is explained in greaterdetail in Syntax for the Snapshot Tool

Operation ValuesThe following table describes the operation values available when entering a Snapshot command. Thesevalues replace the Operation variable in the command line. These values are case sensitive.

Value Description

CRS_SNPSHT Processes a Snapshot feed of Courses.

CRS_MANUAL Performs a manual update of Courses.

CRS_REMOVE Removes the specified list of Courses.

CRS_COPYINTO Copies Course content into an existing Course.

ENR_SNPSHT Processes a Snapshot feed of enrollment.

ENR_MANUAL Performs a manual update of enrollment.

ENR_REMOVE Removes the specified list of enrollments.

ORG_SNPSHT Processes a Snapshot feed of Organizations.

ORG_MANUAL Performs a manual update of Organizations.

ORG_REMOVE Removes the specified list of Organizations.


9.1 S

P6 BETA D

RAFT


Value Description

ORG_COPYINTO Copies Organization data into an existing Organization.

USR_SNPSHT Processes a Snapshot feed of users.

USR_MANUAL Performs a manual update of users.

USR_REMOVE Removes a feed of users.

STAFF_SNPSHT Processes a Snapshot feed of Instructors and Staff.

STAFF_MANUAL Performs a manual update of Instructors and Staff.

STAFF_REMOVE Removes all Instructors and Staff in the feed file.

ORGMEM_SNPSHT Processes a Snapshot for Organization membership.

ORGMEM_MANUAL Performs a manual update for Organization membership.

ORGMEM_REMOVE Removes all Organization memberships in the feed file.

CRS_CATEGORY_SNPSHT To process a Snapshot feed of Course categories.

CRS_CATEGORY_MANUAL To process a manual feed of Course categories.

CRS_CATEGORY_REMOVE Removes all Course categories specified in the feed file.

CRS_CATEGORY_MEM_SNPSHT To process a Snapshot feed of Course Category Memberships.

CRS_ CATEGORY_MEM _MANUAL To process a manual feed of Course Category Memberships.

CRS_ CATEGORY_MEM _REMOVE Removes all Course Category Memberships specified in the feed file.

ORG_CATEGORY_SNPSHT To process a Snapshot feed of Organization categories.

ORG_CATEGORY_MANUAL To process a manual feed of Organization categories.

ORG_CATEGORY_REMOVE Removes all Organization categories specified in the feed file.

ORG_ CATEGORY_MEM _SNPSHT To process a Snapshot feed of Organization Category Memberships.

ORG_ CATEGORY_MEM _MANUAL To process a manual feed of Organization Category Memberships.

ORG_ CATEGORY_MEM _REMOVE Removes all Organization Category Memberships specified in the feedfile.

INSTITUTION_ROLE_MEM_MANUAL Performs a manual update for Institution RoleStudents.

INSTITUTION_ROLE_MEM_REMOVE Removes all Institution RoleStudents in the feed file.

INSTITUTION_ROLE_MEM_SNPSHT To process a Snapshot feed of Institution RoleStudents.

OBSERVER_ASSOCIATION_MANUAL Performs a manual update for Observer associations.

OBSERVER_ASSOCIATION_REMOVE

Removes all Observer associations specified in the feed file.

OBSERVER_ASSOCIATION_SNPSHT To process a Snapshot feed of Observer associations.

XML FilesThe following table describes the valid operation commands for handling XML files.

Value Description

XML_SNPSHT Performs a Snapshot on an IMS-compliant XML file.

XML_MANUAL Performs a smart update on an IMS-compliant XML file.


9.1 S

P6 BETA D

RAFT


Value Description

XML_REMOVE Removes the entities specified in the IMS-compliant file.

XML_COPYINTO Processes an XML copyinto feed.

Snapshot Override ModeSnapshot Override is a special mode of Snapshot that has its own format to allow the Data Source Key to bespecified from the command line rather than in the Properties File. This can save time by allowing for a quickupdate without having to create a new properties file.

Snapshot Override FlagsSnapshot Override commands consist of the following components:

l The “-D” flag and the Data Source Key that will be used to override the current one in the PropertiesFile

l the “-f” flag and the invocation (command) that is to be runl the “-t” flag and the full path location to the Feed Filel the “-C” flag and the full path location to the Properties Filel the “-V” flag and the fully-qualified domain name of the virtual host that will be used

Flags are case sensitive, so an upper case “D” needs to be used to denote the Data Source Key, an upper case“C” needs to be used to denote the full path name to the Properties File and an upper case “V” needs to be usedto denote the virtual host name. The “f” and “t” flags are in lower case.

ExampleThe syntax for an entire Snapshot Override commandwill look something like this:

Snapshot_override "-Ddata.source.key=[key] –f [Snapshot Action] –t [feed file] –C[properties file] –V [fully-qualified server name]

Taking the above criteria, a sample Snapshot Override syntax can be built like this:

Snapshot_override "-Ddata.source.key=fall_COURSES_05" –f CRS_SNAPSHOT –tc:\snapshotstuff\feedfiles\fallCourses.csv –C c:\snapshotstuff\snapshot.properties –V"blackboardserver.acme.edu"

Setting Up SOAP for Use with the APISOAP (Simple Object Access Protocol) is an XML format that handles the execution of server side coderemotely, using theWeb. Blackboard Learn supports SOAP implementation of Loaders and Persisters in theEvent Driven APIs. SOAP is activated through a change to the configuration. When this change is made, theDSM Tool and Snapshot will both use SOAP.

Configuration ChangeThe DSM Tool and Snapshot share an environment file, which can be altered to use SOAP. This file is locatedat Blackboard/apps/snapshot/config/env.cmd.

By default the config file is configured directly to the database as:

CONFIG_FILE=%bbdir%\config\service-config-snapshot-jdbc.properties

To implement SOAP, change the property to read:


9.1 S

P6 BETA D

RAFT


CONFIG_FILE=%bbdir%\config\service-config-snapshot-soap.properties

Command Line SyntaxWhen running the invocation through SOAP, the integration user account password informationmust be addedas shown. "Script" is either dsm or snapshot:

script –P "password" [additional flags]

Using an SSL ConnectionAdministrators may choose to use an SSL connection for SOAP Snapshots. The following instructions can beused for bothWindows and UNIX systems.

Locate the SSL CertificateCheck that the server SSL certificate is in X.509 form. If not, export the server’s SSL certificate to a file. OnWindows, use the Certificate Export Wizard to export the certificate. On Unix, the certificate is located at thepath set in /usr/local/blackboard/apps/httpd/conf/ssl.conf.

Import the Server SSL Certificate to the cacerts keystore on the ClientThe cacerts keystore is located in the Java JDK installation under jre/lib/security/cacerts. Use thekeytool to import the server certificate, for example:

keytool –import –file /usr/local/blackboard/apps/httpd/conf/certs/server.crt –keystore/usr/java/jdk1.6.0_18/jre/lib/security/cacerts –trustcacerts

The Administrator will be prompted for a keystore password. The default keystore password for cacerts is“changeit”. The Administrator may change that password using the keytool.

The server certificate may also be imported to a different keystore, but the Administrator should check the rootCertificate Authority (CA) certificate from the issuing Certificate Authority exists in the cacerts keystore.

The above are simplified instructions. For more details on importing SSL certificates and working with the Javakeystore, please consult the "keytool" documentation on Sun's web site. Choose the appropriate link for yourplatform:

UNIX: http://java.sun.com/javase/6/docs/technotes/tools/solaris/keytool.html

Windows: http://java.sun.com/javase/6/docs/technotes/tools/windows/keytool.html

Edit the service-config-snapshot-soap.properties FileIn this file, change the following key values:

blackboard.service.soap.param.encrypt=true

blackboard.service.soap.param.truststore=location of keystore

where location of keystoreis replaced by the path to the keystore (see Step 2).

Initialize persistence with SOAPSimple Object Access Protocol (SOAP) is a set of conventions used for invoking code using XML over HTTP.When programming using the Event Driven APIs, the SOAP password (MD5 encrypted) must be passed whenrun from a client.

ExampleSystem.getProperties().setProperty(CIConstants.REMOTE_PASSWORD,"password");


9.1 S

P6 BETA D

RAFT

http://java.sun.com/javase/6/docs/technotes/tools/solaris/keytool.html

http://java.sun.com/javase/6/docs/technotes/tools/windows/keytool.html


java "-Dremote.access.password=password"

Data MappingTo integrate institutional systems data with Blackboard Learn institutional data attributes must bemapped toattributes in the Blackboard Learn Data Dictionary. The Blackboard Learn Data Dictionary is presented in aseries of tables that begin with Category Data Feed Elements.

Blackboard Learn AttributesBlackboard Learn has aminimal set of required attributes (fields) for records of each entity type. This minimalset of attributes provides the basic integration capability. By using additional attributes available in BlackboardLearn, more complex integration can be performed for a richer andmore convenient online learning experience.

Ownership of InformationOnly authorized personnel should have access to the systems to perform changes. An “ownership” flagdetermines whether data is considered to be owned (controlled) by the institutional system, or whether changesare allowed through the Blackboard Learn user interface. Designating an attribute as owned by the institutionalsystem will override any changes to that attributemade through the user interface. For example, if a user wereto change their password through the UI, the next time data was transferred from the institutional system, thepassword attribute would be overwritten if that attribute were owned by the institutional system. Conversely, ifthe data is owned by the a Course, a change from the institutional system will not override the change inBlackboard Learn.

Note: Institution systems will not contain data corresponding to every attribute in Blackboard Learn. Data thatappears only in a Course should not be owned by the institution system.

Data in Multiple Enterprise SystemsFor data records that appear in multiple institution systems, a decisionmust bemade as to which system’srecords will override the other system’s records during data integration, ensuring the newest or most relevantdata is in the Blackboard database. For example if data is integrated from a Student Information System (SIS)as well as data from an Alumni database, one system key must take precedence over the other. This can beaccomplished in two different ways:

l Develop logic that filters out non-authoritative data as the feed files are created.

-or-

l Enter all the data into a Snapshot feed file but make sure the authoritative data is entered last.

About Snapshot AutomationThere are different places within the workflow of data integration where automation can occur. Automationdepends upon custom built tools containing scripts that process the extraction of institutional data fromdifferent systems, formatting the extracted data, and control the timing and processing of the Properties andFeed Files.

The Snapshot GeneratorThe Snapshot Generator is a utility usually written by each institution. This utility extracts data from the StudentInformation System (SIS) or other database external to Blackboard Learn and formats it for input into theSnapshot process, one file per type per data source. In automated environments it is used in conjunction withthe Snapshot Controller.


9.1 S

P6 BETA D

RAFT


The Snapshot ControllerThe Snapshot Controller is a utility that is written tomanage daily data feeds created by a "snapshot generator"and feed them to the Snapshot tool. The controller automates andmanages the process from the time a datafeed leaves the Snapshot Generator until it reaches the Blackboard Learn database. The Snapshot Controller isusually provided by Blackboard Consulting. It can be customized for each institution so that it can direct emailto appropriate people if a failure occurs in the process, making failure handling relatively simple during theSnapshot process.

Note: The Snapshot Controller is not necessary for Data Integration. The Snapshot Controller is not includedwith the Blackboard Learn andmay be written by the institution.

Process Diagram for AutomationTo automate Snapshot a certain workflow needs to be followed, although the programming for each step will bedifferent for each institution. The process diagram illustrates the work flow.

Snapshot Automation Process Diagram


9.1 S

P6 BETA D

RAFT


About the Snapshot Properties FileThe Properties File instructs the Snapshot tool how to interpret and apply the data in the Feed File to theBlackboard Learn database.

While Blackboard supplies a sample Properties File in the snapshot directory (snapshot.properties) thisfile can be renamed and several different versions can be created and used for different processing jobs. Thetypical items modified in the Properties File are the entry for the Data Source Key, the delimiter used in the feedfile, and the list of Blackboard-owned fields.

The Snapshot tool provides different modes depending on the specific task it will be used to perform. Thissection provides a description of eachmode, and how to invoke them using the command line syntax.

About Feed FilesThe data that is fed into Blackboard Learn to create users, courses, update records and so on exists in a “feedfile”. Snapshot Feed Files can be character-delimited flat files or XML files that conform to IMS standards.Blackboard adheres to the Global Community XML encoding standards, which commonly uses UTF–8. Thischapter reviews in detail the format of Snapshot flat files and provides a link to information about IMS standardsfor XML files.

To accept Multi-byte information, files must be in Unicode format. All Unicode formatted files must include theByte Order Mark (BOM). If a BOM is not specified, the system reads it as ISO-8859-1. The supported formatsare as follows:

l UTF-8l UTF-16LEl UTF-16BEl ISO-8859-1

ASCII is also a supported format, since it is a subset of ISO-8859-1.

Using Delimiters and Escape CharactersFor data to be parsed correctly from a Feed File, Snapshot needs to know where the data for each different fieldends. A character that does not regularly appear in the data is usually selected as the “delimiter” – the characterthat separates one field from another in a row. The “|” pipe character is the default delimiter character in theProperties File.

Occasionally the delimiter character will appear in the data. Unless the system knows that this particularinstance of the delimiter character is actually part of the data itself and not denoting the division of a field, thedata feed will contain errors or fail all together. In order to tell the system that a particular delimiter character ispart of the data set it must be “escaped”.

To be able to escape a delimiter, an escape character is defined in the Properties File. The “/” character is thedefault escape character.

How to Change the DelimiterTo change the default delimiter character, edit the Properties File. Any SQL character may be used as adelimiter. Find the line in the Properties File that reads:

# delimiter used for parsing snapshot files

data.delimiter=|


9.1 S

P6 BETA D

RAFT


Change the character on the right side of the equals “=” sign to the desired character. If this character appearsin a data field, it must be escaped in every field where it occurs. For this reason, selecting a character thatmight commonly appear in the data fields is not to be recommended.

How to Change the Escape CharacterTo change the default escape character, edit the Properties File. Find the line in the Properties File that reads:

# Determines character used to escape delimiter

escape.character=/

Change the character on the right side of the equals “=” sign to the desired character. This character wouldprecede any delimiter character that appears in all data fields. For example, if the hyphen “-” has been set as thedelimiter, every time a hyphen appeared in a data field it would be escaped by placing the “/” character before it.In the example below, the last name is Smith-Jones, so the hyphen in the last namemust be escaped like this:

EXTERNAL_PERSON_KEY-USER_ID-SYSTEM_ROLE-FIRSTNAME-LASTNAME-EMAIL-INSTITUTION_ROLE

2000-jsmithjones100-none-John-Smith/[email protected]

Using the Snapshot XML Feed File FormatCompared to a flat file feed, an XMLSnapshot file has increased flexibility in that the XML files can process onedata type at a time, or combinemultiple data types to be processed at once. While Blackboard Learn does notvalidate against the XMLData Dictionary defined in Data Format Tables for XML Files, the codemust be well-formed, meaning each nested tagmust be properly closed.

The Snapshot Tool will process IMS compliant XML files, version 1.01. For information about IMS standards forXML files, view the followingWeb page on the IMS site:

http://www.imsproject.org/enterprise/enbind03.html

Since entities in the XML file are typed, there are no specific requirements to separate entities into separateFeed Files. However, the action and data source attributes specified in the IMS standard are ignored. Inprocessing the IMS XML format, the Blackboard Learn Snapshot Tool still requires the same logic and workflowas used with a flat file.

XML Template TagsThe following refer to specific tags in the XML template:

l Extension tags: These tags are not supported in the IMS specifications; they are only supported byBlackboard Learn. As they are adopted by the IMS project, Blackboard will phase them into properXML definition.

l Categories and Category Memberships: These are not IMS data types and are not supported by IMS;they are supported by Blackboard Learn.

The following tips are helpful for troubleshooting Snapshot XML files:

l If a user fails to be created in an XML file then their membership will also fail. Many aspects of theXML file are related, therefore is one area fails, it may cause others to also fail.

l Blackboard recommends using an XML viewer when viewing the .invalid file (error log). This fileshould be referenced if an error occurs.

XML Feed File ExampleAn example of an XML Feed File can be view in Data Format Tables for XML Files.


9.1 S

P6 BETA D

RAFT

http://www.imsproject.org/enterprise/enbind03.html


Using the Snapshot Flat Feed File FormatThe Snapshot Feed File can be a “flat file”, another term for a delimited text file. A Feed File may encompassinformation about any of the ten entities that are transferred to Blackboard Learn. A Feed File consists of aheader row that identifies each of the columns or fields of data followed by one or more rows of data records.

Header RowThe Header Row in a Feed File contains Field Names, which are the exact names of the fields included in thefile. These names are listed in the tables in the feed file topics, starting with Category Data Feed Elements. Theheader fields are delimited with the same character as the data records.

Fields can appear in the header row in any order, but fields not recognized by Blackboard Learn cannot beincluded or errors will occur or the operation will fail completely.

Note: Snapshot feed files work in both Right to Left and Left to Right operating system environments. Theorder of the fields in the header row is not important, only that it matches the order of the data rows. Thedelimiter for Snapshot feed files used in a Right to Left environment must be a Tab. The commonly used pipe ( |) can cause some fields to reverse order, misaligning the header row with the data rows.

Each Feed File type has aminimum number of required fields that need to be identified in the header row.

Theminimum required fields for a user Feed File are:

l EXTERNAL_PERSON_KEYl USER_IDl SYSTEM_ROLEl FIRSTNAMEl LASTNAMEl EMAILl INSTITUTION_ROLE

Theminimum required fields for a Course or Organization Feed File are:

l COURSE_IDl EXTERNAL_COURSE_KEYl COURSE_NAME

Theminimum required fields for an enrollment or staff Students Feed File are:

l EXTERNAL_COURSE_KEYl EXTERNAL_PERSON_KEYl ROLE

An example of a header row for a user Feed File:

EXTERNAL_PERSON_KEY|USER_ID|SYSTEM_ROLE|FIRSTNAME|LASTNAME|EMAIL|INSTITUTION_ROLE

Data RowsAfter the header row, data records, one per line are added to the Feed File. Records are separated by a carriagereturn, a linefeed or the combination of the two. The record separator is not configurable.

Some data feed elements have sets of string constants for their possible values. For example, the attributeInstitution_Rolemaps to coded characters in the database.


9.1 S

P6 BETA D

RAFT


l Strings that exceed the specifiedmax length for that columnwill be truncated. Data Source Keys thatexceed the specifiedmax length for that columnwill cause the record to fail.

l Data types that cannot be converted (such as dates) are ignored. (They are treated as a space or asmissing.)

l Invalid column headers are ignored.

Note: Unsupported feed elements will not cause the feed to fail—they are ignored to preserve backwardcompatibility with older feed generators.

Setting Up Integration Tools on a Client MachineIn certain situations, it can be advantageous to install integration tools on a client machine. The client tools canprocess the Snapshot files instead of the application server, leavingmore of the application server resourcesavailable to handle other tasks.

Installing the Client SoftwareUse the following steps to install Blackboard Learn client tools. Themost recent version of JDK 1.6.0 isrequired to run the client tool.

How to Install on Windows1. Download the Snapshot Client Installer from

https://behind.blackboard.com/s/sysadminas/dlc/tools.aspx2. From the directory the file was unpacked into, run the appropriate Blackboard9Client_

windows file.3. Read and accept the License Agreement.4. Click Browse to locate and select a License file.5. Select the directory where the client tools will be installed. If left blank, a Blackboard directory will

be created.6. Enter the location of the JDK.7. Enter the database server information, including, the databasemachine name, the database

domain, SQL® Server Instance Name (if not using the default), the BbAdmin database userpassword and confirm the password.

8. The database server location information.

How to Install on UNIX1. Download the Snapshot Client Installer from

https://behind.blackboard.com/s/sysadminas/dlc/tools.aspx.2. From the directory the file was unpacked into, run the appropriate file for the operating system.

After downloading the file check that it is executable.Blackboard9Client_linux

Blackboard9Client_solaris

3. Accept the license agreement.4. Enter the full path to the license file including the name of the file.5. Specify the directory that will hold the client tools.6. Enter the path to the JDK directory.


9.1 S

P6 BETA D

RAFT

https://behind.blackboard.com/s/sysadminas/dlc/tools.aspx

https://behind.blackboard.com/s/sysadminas/dlc/tools.aspx


7. Enter the databasemachine name, database domain name, Oracle SID, and bbadmin databaseuser password.

Note: If the databasemachine is not resolved on the DNS server then it must be resolved in the /etc/hosts fileof the local machine that will run the client tools.

Confirm that all the information entered is correct and proceed with the installation.

CLASSPATHImplementations must include the following .jar files in the CLASSPATH to use the event-driven API tools. Thisstep is not necessary for clients using just the snapshot tool.

Windows\blackboard\systemlib\bb-platform.jar

\blackboard\systemlib\cms-admin.jar

\blackboard\systemlib\bb-snapshot.jar

\blackboard\systemlib\jdbc\Opta2000.jar

\blackboard\systemlib\jdbc\jdbc2_0-stdext.jar

\blackboard\systemlib\xerces-1.4.3.jar

\blackboard\systemlib\gnu-regexp-1.0.8.jar

\blackboard\systemlib\gnu-getopt-1.0.8.jar

\blackboard\systemlib\servelet.jar

\blackboard\systemlib\mail.jar

\blackboard\systemlib\activation.jar

\blackboard\systemlib\soap.jar

UnixThe required .jar files are added to the CLASSPATH during installation. In most cases, they only need to bemanually added to the CLASSPATH of other institutional systems that will make use of the Event Driven API.Web services must be restarted after changing the CLASSPATH.

/blackboard/systemlib/bb-platform.jar

/blackboard/systemlib/cms-admin.jar

/blackboard/systemlib/bb-snapshot.jar

/blackboard/systemlib/jdbc/Opta2000.jar

/blackboard/systemlib/jdbc/jdbc2_0-stdext.jar

/blackboard/systemlib/xerces-1.4.3.jar

/blackboard/systemlib/gnu-regexp-1.0.8.jar

/blackboard/systemlib/gnu-getopt-1.0.8.jar

/blackboard/systemlib/servelet.jar

/blackboard/systemlib/mail.jar

/blackboard/systemlib/activation.jar

/blackboard/systemlib/soap.jar


9.1 S

P6 BETA D

RAFT

Backup and Recovery > Windows

Backup and Recovery

Windows

About Backup and RecoveryThis topic offers some tips on system-wide backups and describes the tools in Blackboard Learn forincrementally backing up Courses andOrganizations.

System Backup and RecoveryAdministrators should backup the database and file system according to the needs of the Institution.Blackboard Learn supports full backup and restores at the operating system and database levels. As a generalrule, daily backups should be kept for two weeks, as errors may not appear for several days. Recovery plansshould include how to restore the entire system. For assistance restoring the system, contact BlackboardTechnical Support by logging in to Behind the Blackboard at https://behind.blackboard.com.

Incremental Data ProtectionBlackboard Learn includes the following utilities for incrementally backing up individual Courses andOrganizations:

l Export/Import: Export takes Course content and puts it in a package that can be used in anotherCourse at a later date. One or more Course areas can be included in the package.

l Archive/Restore: The Archive Course function creates a record of the Course including userinteractions. It is most useful for recalling Student performance or interactions at a later time. Thearchive package is saved as a .ZIP file that can be restored to the system at another time.

The command line tool that processes batch operations for Export/Import and Archive/Restore is a powerfultool for backing up Course andOrganization data.

Note: The default size limit for content uploaded though the user interface is 250MB. When attempting toupload files larger than 250MB using the interface, users will receive an error. This limit does not apply toWebFolder uploads. To upload larger files, Administrators can upload the files using the command line or they canincrease the Tomcat default size setting. To increase themaximum upload limit, modify the parameter locatedin webapps/blackboard/WEB-INF/config/struts/reporting-struts-config.xml. The filesize upload limit is tied to Tomcat, therefore it is not encountered withWebDAV uploads. Because the settingis tied to Tomcat, the services must be restarted for the change to take effect.

Avoiding Recovery of Files During UpgradeDuring a Blackboard Learn upgrade, items such as custom folders, and archived snapshots which are storeddirectly beneath the blackboard_home directory aremoved to a time-stamped backup directory. Customizedfiles and folders that are not Blackboard-owned will be considered unexpected andmoved to the backupdirectory. To avoid your customized non-Blackboard-owned files from beingmoved during an upgrade, createclient-dirs.txt and client-files in your config directory. List each file and folder's relative path toyour blackboard_home directory on its own line in the respective text file. The files do not accept wildcards,so the files and folders must be specified individually. This methodmust be used with caution to avoid apartially upgraded environment, and if the file is Blackboard-owned and customized it will still be overwrittenwith the new version.


9.1 S

P6 BETA D

RAFT



Resource PlanningVerify that the target databases have sufficient space before restoring Blackboard Learn and the contentmanagement data.

How to Check the Tablespace Sizes in the Source DatabaseExecute the following SQL query to determine the space used by Blackboard Learn in each tablespace:

Blackboard LearnSELECT tablespace_name, SUM (bytes) FROM dba_segments WHERE tablespace_name LIKE 'BB%'GROUP BY tablespace_name;

Example of Output for Blackboard LearnTABLESPACE_NAME SUM(BYTES)

BBADMIN_DATA 1179648

BBADMIN_INDX 1572864

BBLEARN_DATA 178388992

BBLEARN_INDX 53608448

BBLEARN_STATS_DATA 1966080

BBLEARN_STATS_INDX 6553600

Content ManagementSELECT tablespace_name, SUM(bytes) FROM dba_segments WHERE tablespace_name LIKE 'CMS%'GROUP BY tablespace_name;

Example of Output for Content ManagementTABLESPACE_NAME SUM(BYTES)

CMS_DATA 3801088

CMS_DOC 87425024

CMS_INDX 1966080

How to Verify that the Corresponding Target Tablespaces Have SufficientSpaceThe following query can return two or more rows for each tablespace. Each row shows themaximum size ofeach file that belongs to that tablespace. If themaxbytes equals 0, themaximum is unlimited. Some operatingsystems limit the file size to 2GB. Therefore, Blackboard recommends limiting the file size to 2GB even thoughthe operating systemmay be capable of handling larger sizes.

To determine the total size of each tablespace, add all themaxbytes together. If themaxbytes of a tablespaceequals 0, substitute with 2GB before adding themaxbytes together. Execute the following SQL query todeterminemaximum space to which each tablespace can grow:

Blackboard LearnSELECT tablespace_name, maxbytes FROM dba_data_files WHERE tablespace_name LIKE 'BB%';


9.1 S

P6 BETA D

RAFT


Example of Output for Blackboard LearnTABLESPACE_NAME MAXBYTES







Content ManagementSELECT tablespace_name, maxbytes FROM dba_data_files WHERE tablespace_name LIKE 'CMS%';

Example of output for Content ManagementTABLESPACE_NAME MAXBYTES

CMS_DATA 2097152000

CMS_INDX 2097152000

CMS_DOC 2097152000

Insufficient Available SpaceIf themaximum available is not sufficient, there are two options available for increasing the space. Both optionsapply to Blackboard Learn and content management. The first option is to increase the file size (which isrecommended), and the second option is to add one or more files.

How to Increase the File SizeIf the required space in any tablespace is less than 2GB and themaximum available space is not sufficient, thesize of the file may be increased up to 2GB. For example, if BBLEARN_DATA tablespace requires 700MB, butthemaximum available space is only 500MB, increase the file size to 2GB. Before increasing the file size,locate the file name that belongs to the BBLEARN_DATA tablespace.

1. Locate the file name and note the file naming convention. The file naming convention should betablespace_name_filesequential_number.dbf , where the first sequential number is'1'.SELECT file_name FROM dba_data_files WHERE tablespace_name='BBLEARN_DATA';

2. Resize the file.ALTER DATABASE datafile 'path_to_file/bblearn_data_file1.dbf' RESIZE 2000M;

How to Add One or More FilesIf the required space in any tablespace is greater than 2GB and themaximum available space is not sufficient,one or more files must be added to increase the available space. For example, if BBLEARN_INDX tablespacerequires 5GB, but themaximum available space is only 2GB, another two files of 2GB eachmust be added toresult in a total of 6GB. Additional space which is not currently in use does not have a negative impact; and isrecommended for scaling. Use the following steps to add the files.

1. Find the existing file and its path:SELECT file_name FROM dba_data_files WHERE tablespace_name='BBLEARN_INDX';

2. Add two files to increase the available space:


9.1 S

P6 BETA D

RAFT


ALTER TABLESPACE BBLEARN_INDX ADD datafile 'path_to_file/bblearn_indx_file2.dbf' SIZE 2000M;


About Moving Blackboard Learn in a SQL EnvironmentThis section explains how tomove Blackboard Learn and Content Collection files to another server.

Content Collection files are available only if your school licenses content management.

This information applies to all systems using aMicrosoft® Windows® Operating System with a SQL®database. To learnmore about the technologies supported in Blackboard Learn, see theMaintenance Center.

There are several methods and solutions for Administrators interested in establishing regularly scheduledbackups (and associated restore procedures) of SQL databases. Regularly scheduledmaintenance is outsidethe scope of this document. To learnmore, see the documentation supplied by Microsoft.

It is critical to backup the file system at the same time as the databases. When restoring the databases from abackup, be sure to restore the file system to ensure synchronization between the file system and thedatabases.

Moving Content Management FilesAll database and file backups must bemade for the same time frame. For example, databases backed up onSunday and courses backed up from the previous Tuesday will not work. All directory and database backupsshould bemade at the same day and time.

Remember to stop the Blackboard services to ensure that the courses, content, and databases aresynchronized.

All backed up datamust be restored into the same version and build of Blackboard Learn. Do not restore data todifferent builds of either the Blackboard Learn.

Stop the Services1. Launch a command prompt from theWindows Start menu.2. Navigate to blackboard_home\tools\admin3. Stop the iisadmin, bb-collab, and bb-tomcat services by running the following command:

servicecontroller.bat services.stop.

Back Up the Content Management FilesMake a complete backup copy of the Blackboard Learn content file system, directory and the contentmanagement storage directories: blackboard_home\content\vi\BBLEARN\courses

Blackboard also recommends a redundant backup of theblackboard_home\mssql directory for singleserver installations. All Blackboard services must be stopped before backing up the blackboard\mssqldirectory.

The content management directories are as follows:

blackboard_home\content\courses\courses

blackboard_home\content\institution\institution

blackboard_home\content\library\library

blackboard_home\content\orgs\orgs

blackboard_home\content\users\users


9.1 S

P6 BETA D

RAFT




The content management file system directory locations will vary depending on the original storage locationentered during setup.

Create a copy of the blackboard_home\docs\login directory. This is needed only if changes weremadeto the original login page.

Restore the Content Management FilesThe Blackboard services bb-collab, bb-tomcat, and IIS admin and the DFS (Distributed FileSystem) servicemust be stopped on each Application server before restoring the file system content.

Restore the login blackboard_home\docs\login\ folder to restore the special changes to your login page.

One or Two Server ConfigurationsRestore the Blackboard Learn courses data to the new destination server courses folder blackboard_home\content\vi\courses. Content Collection Users should also restore the external storage directoriesto the locations selected during installation.

Load-balanced ConfigurationsStop the DFS service on each web/app server to prevent file sharing violations and perform a restore of theBlackboard Learn courses content to the courses folder \\filesystem_server\bb_content\vi\BBLEARN\courses on the load balanced file system server designated during the setup of yourconfiguration. Content Management content should be restored to the external storage locations designatedduring setup.

Note: If the external storage location paths have changed from the original backup, youmust update thepaths.To learnmore, see Editing the Properties File in a SQL Environment.

Backing up the Database in a SQL EnvironmentBack up the database usingMicrosoft SQL Server 2005 Backup/Restore Utility. Create a current SQL Serverbackup of all the Blackboard databases. If your school licenses content collection, youmust back up additionaldatabases along with the Blackboard Learn databases.

Blackboard Learn Databasesl BBLEARN_ADMIN

l BBLEARN

l BBLEARN_STATS

Blackboard Learn Legacy Databasesl BBADMIN

l BB_BB60

l BB_BB60_STATS

Content Management Databasesl CMS

l CMS_DOC


9.1 S

P6 BETA D

RAFT


Content Management Legacy Databasesl CMS

l CMS_FILES_COURSES

l CMS_FILES_INST

l CMS_FILES_LIBRARY

l CMS_FILES_ORG

l CMS_FILES_USERS

Follow the abbreviated steps below to perform a full backup of all your Blackboard databases using theMicrosoft SQL Server 2005 backup and restore utility. The backup of any data should be scheduled for a timewhen you can turn off access to the Blackboard website. Backup the file system at the same time to ensure asynchronized backup of both file system content and databases.

Stop the Services1. Launch a command prompt from theWindows Start menu.2. Navigate to blackboard_home\tools\admin.3. Stop the iisadmin, bb-collab, and bb-tomcat services by typing the following command

and pressing the ENTER key:servicecontroller.bat services.stop

Configure and Initiate the Backup1. Click Start > All Programs > Microsoft SQL Server 2005 > SQL Server Management Studio.2. Connect to the database and click on the expanded Databases folder to expand the list of

databases.3. Highlight the BBLEARN database and right click themouse on the selected database.4. On thePropertiesmenu point to Tasks, and then click Back Up. The Back UpDatabase dialog

box appears.5. In theBackup Type list box, select Full. For Backup component, click Database. The default

setting is to perform a Full database backup and will append to any existingmedia if available.Accept the default setting for the backup.

6. In theDestination section of the General page, click Disk or Tape. Choose the destination orlocation of the database backup files by clickingAdd. The default location of backups in SQL isunder SQL Server’s directory tree

Example:

C:\All Programs\Microsoft SQL Server 2005\MSSQL\BACKUP\

Blackboard recommends backing up your data to an alternate location. If there is a need to reinstallSQL Server the data files for your Blackboard application will be protected from accidental deletionduring an SQL Server uninstall and reinstall.

Example:

D:\SQL\MSSQL\BACKUP\

The remaining SQL backup steps will outline how to backup to a new Backup Device location.


9.1 S

P6 BETA D

RAFT


7. After clickingAdd, under theDestination field, a new window opens showing the default locationto store the backup. Do not accept the default location. Click Browse to find a new backup devicelocation directory on the local server.

8. Browse to the new directory location and highlight the new directory.9. Enter a name in the file name field at the bottom of the Destination for the backup files using the

.bak as the extension. Adding the extension will allow SQL Server to recognize the file type for allyour database backup files.

Example:

dates-01122010.bak for January 12, 2010 or names-BBLEARN.bak for one time backups

Select the type of storage device the backup should be stored to, Disk or Tape.

10. Click OK to accept the new device location and file name. Click OK again to close the SelectBackup Destination window.

11. From theOptions page, underReliability, select theVerify backup when finished button tocomplete the backup procedure.

12. Click OK to start the database backup. The backup has completed when themessage shows thatthe backup operation and verification completed successfully.

13. Repeat the above steps for each Blackboard Learn and content management database.

Setting Up Target System in a SQL Environment

How to Check the Ownership of Tables and Stored Procedures in SQLServer

1. Click Start > All Program > Microsoft SQL Server 2005 > SQL Server Management Studio.2. Expand the Databases folder to expand down to the BBLEARN database. Expand that level to view

all components of the BBLEARN database.3. Select the Tables folder in the left pane to show all tables in the BBLEARN database.4. Double-click theSchema column in the right pane to sort the column values. All items should be

owned by dbo. Scroll through the list to ensure all items are owned by dbo. Repeat this step for theStored Procedures folder in the BBLEARN database. Double-click theSchema column to sort thecolumn values. All items should be owned by dbo.

How to Change the Ownership of an Object in SQL ServerBrowse the tables and stored procedure by clicking on the tables or stored procedure folders in the SQL ServerManagement Studio. Look for tables or stored procedures owned by user BBLEARN. Make a list of each table orstored procedure found that will require a change of ownership. Use the following steps to change theownership:

1. Click Start > All Program > Microsoft SQL Server 2005 > SQL Server Management Studio.2. Expand the Databases folder to expand down to the BBLEARN database.3. Highlight the BBLEARN database.4. Click New Query to openQuery Analyzer.5. Copy the following statement into the query window:

sp_changeobjectowner ‘BBLEARN.BBLEARN.$object_name$’, ‘dbo’

6. Insert the name of the table or stored procedure into the above query that needs to be changed fromBBLEARN to dbo in to the $object_name$ field.


9.1 S

P6 BETA D

RAFT


Stored procedure change example:

sp_changeobjectowner 'BBLEARN.BBLEARN. attempt_cp’,'dbo'

Table change example:

sp_changeobjectowner ‘BBLEARN.fix_gradebook_main','dbo'

7. Select Run or press F5 to execute the edited query. The followingmessage will be displayed,which indicates that the ownership has been changed successfully.

Caution: Changing any part of an object name could break scripts and stored procedures.

8. Repeat Steps 1 through 7 to change each stored procedure and/or table from BBLEARN to dbo.9. After completing the change object ownership, the Administrator must re-run the restore script from

this document and proceed with the remaining steps in the data restore.10. Restart the server or servers.

Note: The restore script must be executed again after changing the ownership of an object. If it is not, theapplication will not connect to the database after completing the remaining steps in the restore document.

How to Change the Hostname Settings to Match the New ServerThe following SQL queries must be run on the new server to change the hostname and fullhostnamevalues within the BBLEARN_ADMIN database, assuming these values have changed.

The two BBLEARN_ADMIN tables that are updated are the bbadmain.bb_instance table and theBBLEARN_ADMIN.bb_instance_host table. The update is performed after the data is restored to a newdestination server.

1. Click Start > All Programs > Microsoft SQL Server 2005 > SQL Server Management.2. Click on the expanded Databases folder to expand to the BBLEARN_ADMIN database.3. Highlight the BBLEARN_ADMIN database.4. Click New Query to openQuery Analyzer.5. Update the db_host, db_pass, stat_db_host, and stat_db_pass for each BBUID. The

first BBUID is called BBLEARN by default. If the port numbers are different, thesemust beupdated.BB_INSTANCE TABLE

UPDATE bb_instance SET

db_host = 'NEW_DB_HOST_NAME',

db_pass = 'NEW_PASSWORD',

stat_db_host = 'NEW_STAT_DB_HOST_NAME',

stat_db_pass = 'NEW_STAT_DB_PASSWORD'

Where bbuid = 'BBLEARN';

6. Click Run or F5 to execute script after loading it into the query window.7. The bb_instance_host table contains the fullhostname that is used to access the

blackboard server using the URL.

Example:

hostname.domain_name.com

BB_INSTANCE_HOST TABLE

UPDATE bb_instance_host SET hostname= 'TARGET_HOST_HAME.domain_name.com'

WHERE hostname= 'SOURCE_HOST_NAME.domain_name.com';


9.1 S

P6 BETA D

RAFT


Editing the Properties File in a SQL EnvironmentThe application paths must be updated whenmoving to a new drive after reinstalling. When the backed up datais restored the original drive letter and old directory location will prevent the restored databases fromconnecting.

To update the application path in the database, run the PushConfigUpdates.bat command line tool.Running PushConfigUpdates.bat also ensures that the application software and the restored databasesare using the same database passwords and users to communicate. To learnmore, see PushConfigUpdates.

How to Update Blackboard Learn Properties1. Click Start > Run. Type CMD and click OK to launch the commandwindow.2. Change directories by typing the following at the command prompt, and pressing the ENTER key.

X:\> cd blackboard\tools\admin

3. List the contents on the directory by typing dir at the command prompt and pressing the ENTERkey.

Example:

blackboard_home\tools\admin\dir

4. Find the PushConfigUpdates.bat file in the list, and then run the PushConfigUpdates batchfile by typing the following command and pressing the ENTER key.PushConfigUpdates.bat

5. The PushConfigUpdates.bat file will apply the new environment variables to the restoreddatabases. This will update the drive paths in the databases to the ones listed in the configurationfiles created after the fresh install of Blackboard on the new drive.

Note: The PushConfigUpdates.bat file will take a period of time to run andmay appear tohave stalled. This is normal and the Administrator must wait until the file has finished.

6. Reboot the server and login to test.

How to Update the Content Management PropertiesUpdate the Blackboard CMS External Storage paths to reflect the new drive location on the new server.

1. Click Start > Program Files > Microsoft SQL Server > SQL Enterprise Manager.2. Click on the expanded Databases folder to expand to the CMS database.3. Highlight the CMS database.4. Click New Query to openQuery Analyzer.5. Copy the following SQL statement for CMS into the query window and insert the new windows_

storage_location. Click Run or press F5 to execute the script after loading it into the querywindow.UPDATE XY_STORAGE_LOCATIONS

SET WINDOWS_STORAGE_LOCATION='blackboard_home\content\users'

WHERE STORAGE_LOCATION_ID= '1001';

UPDATE XY_STORAGE_LOCATIONS

SET WINDOWS_STORAGE_LOCATION='blackboard_home\content\courses'




9.1 S

P6 BETA D

RAFT


SET WINDOWS_STORAGE_LOCATION='blackboard_home\content\orgs'



SET WINDOWS_STORAGE_LOCATION='blackboard_home\content\institution'



SET WINDOWS_STORAGE_LOCATION='blackboard_home\content\library'


Note: Where X: is the new destination path for the external storage locations. If drivemappings are beingused for load balanced clients remember to enter themapped drive letter not the physical drive.

How to Synchronize PasswordsRun the blackboard_home\apps\bbcms\bin\push-cs-config-update command to update thecontent managementdb_user password in the restored databases. This will sync the database passwordbetween the application and the restored CMS database.

1. Click Start > Run. Type CMD and click OK to launch the commandwindow.2. Change directories by typing the following at the command prompt, and pressing the ENTER key.

cd blackboard_home\apps\bbcms\bin

3. Run the push-cs-config-update.bat file by typing the following command and pressing theENTER key.cs-config-update.bat

4. Login to the Blackboard web site to test the installation once the script is complete.5. Reboot the server or servers and test the system.

Restoring the Database in a SQL EnvironmentThe database restore will fail if you do not stop the Blackboard services and any other applications connectingto SQL during the restore procedure. The restore of any data should be scheduled for a time when you can turnoff access to the Blackboard website.

Stop the Services1. Launch a command prompt from theWindows Start menu.2. Navigate to blackboard_home\tools\admin.3. Stop the iisadmin, bb-collab, and bb-tomcat services by typing the following command

and pressing the ENTER key:servicecontroller.bat services.stop

Restoring Databases to Existing Hardware1. Click Start > All Programs > Microsoft SQL Server 2005 > SQL Server Management Studio.2. Connect to the database and click on the expanded Databases folder to expand the list of

databases.3. Highlight the BBLEARN database and right click on the Database.4. Click Properties > Tasks > Back Up to open the SQL Backup Utility. The default settings of the

restore database window shows the last known verified backup checked. Accept the default


9.1 S

P6 BETA D

RAFT


settings for this restore if it is the correct backup. Confirm the date/time stamp or name of yourbackup before proceeding.

5. Click Database to select your backups from the alternate databases if the default database listedis incorrect. This will navigate to the alternate backup directory on your server.

6. Navigate toDestination. This will allow you to choose the location of your backup file.a. Click Add to open the Select Backup Destination window shown.b. ClickBrowse to open the Locate Database Files window shown.c. Browse to the backup directory and select the correct data files. The file namewill

show in the window once highlighted.d. Click OK to accept the file name chosen.e. Click OK again to close the window and return to the Restore database window.

7. Confirm that the backup data file is correct. Click on theOptions page to proceed to the next step.8. Check Overwrite all existing backup sets underOverwrite media.9. Click OK to start the restore of the database. Wait for themessage that the restore has completed.

Restore Databases to New Hardware1. Restore the Blackboard Learn databases and content management databases using the steps to

restore databases on existing hardware as detailed previously.

2. Check the ownership of tables and stored procedures in the restored databases before proceedingto the restore script. For detailed instruction, see Setting Up Target System in a SQL Environment.

3. Click Start > All Programs > Microsoft SQL Server 2005 > SQL Server Management Studio.4. Expand the Databases folder to expand down to the BBLEARN database.5. Highlight the BBLEARN database.6. Click New Query.7. Copy one of the following statements into the query window. There are separate queries for

Blackboard Learn and content management. Make sure to run the right query.8. Click Run or F5 to execute script after loading it into the query window.

Restore Script for Blackboard Learn Only (Non-legacy)Use BBLEARN

Go

sp_dropuser BBLEARN

Go

sp_dropuser BBLEARN_report

Go

sp_dropuser BBLEARN_stats

Go

Use BBLEARN_stats

Go


Go

Use BBLEARN_ADMIN

Go


9.1 S

P6 BETA D

RAFT


sp_dropuser BBLEARN_ADMIN

go

sp_dropuser BBLEARN

go


Go

Use BBLEARN_ADMIN

Go

sp_grantdbaccess BBLEARN_ADMIN

go

sp_grantdbaccess BBLEARN

go

sp_grantdbaccess BBLEARN_stats

Go

sp_addrolemember db_owner, BBLEARN_ADMIN

go

sp_addrolemember db_datareader, BBLEARN

go

sp_addrolemember db_datareader, BBLEARN_stats

Go

Use BBLEARN

Go

sp_grantdbaccess 'BBLEARN'

Go

sp_grantdbaccess 'BBLEARN_report'

Go

sp_grantdbaccess 'BBLEARN_stats'

Go

sp_addrolemember 'db_owner', 'BBLEARN'

Go

sp_addrolemember 'db_datareader', 'BBLEARN_stats'

Go

Use BBLEARN_stats

Go


Go

sp_addrolemember 'db_owner', 'BBLEARN_stats'

Go

—-SQL Server 2000 database compatible level to SQL Server 2005

EXEC sp_dbcmptlevel BBLEARN, 90;

GO

EXEC sp_dbcmptlevel BBLEARN_stats, 90;

GO

EXEC sp_dbcmptlevel BBLEARN_ADMIN, 90;

GO


9.1 S

P6 BETA D

RAFT


Combined Restore Script for Both Blackboard Learn and ContentManagement (Containing Legacy Databases)Use BBLEARN

Go

sp_dropuser BBLEARN

Go

sp_dropuser BBLEARN_report

Go


Go

Use BBLEARN_stats

Go


Go

Use BBLEARN_ADMIN

Go

sp_dropuser BBLEARN_ADMIN

Go

sp_dropuser BBLEARN

Go


Go

Use BBLEARN_ADMIN

Go

sp_grantdbaccess BBLEARN_ADMIN

Go

sp_grantdbaccess BBLEARN

Go

sp_grantdbaccess BBLEARN_stats

Go

sp_addrolemember db_owner, BBLEARN_ADMIN

Go

sp_addrolemember db_datareader, BBLEARN

Go

sp_addrolemember db_datareader, BBLEARN_stats

Go

Use BBLEARN

Go

sp_grantdbaccess 'BBLEARN'

Go

sp_grantdbaccess 'BBLEARN_report'

Go


Go


9.1 S

P6 BETA D

RAFT


sp_addrolemember 'db_owner', 'BBLEARN'

Go

sp_addrolemember 'db_datareader', 'BBLEARN_stats'

Go

Use BBLEARN_stats

Go


Go

sp_addrolemember 'db_owner', 'BBLEARN_stats'

Go

—-SQL Server 2000 database compatible level to SQL Server 2005

EXEC sp_dbcmptlevel BBLEARN, 90;

Go

EXEC sp_dbcmptlevel BBLEARN_stats, 90;

Go

EXEC sp_dbcmptlevel BBLEARN_ADMIN, 90;

Go

Use cms

Go

sp_dropuser cms_user

Go

Use cms_files_courses

Go


Go

Use cms_files_inst

Go


Go

Use cms_files_library

Go


Go

Use cms_files_orgs

Go


Go

Use cms_files_users

Go


Go

Use cms

Go

sp_grantdbaccess cms_user

Go


9.1 S

P6 BETA D

RAFT


sp_addrolemember db_datareader, cms_user

Go

sp_addrolemember db_datawriter, cms_user

Go

Use cms_files_courses

Go


Go


Go


Go

GRANT EXEC ON XYF_PERMISSIONS TO cms_user

Go

GRANT EXEC ON XYF_BLOB_WRITE TO cms_user

GO

Use cms_files_inst

Go


Go


Go


Go


Go


GO

Use cms_files_library

Go


Go


Go


Go


Go


GO

Use cms_files_orgs

Go


Go



9.1 S

P6 BETA D

RAFT

Backup and Recovery > UNIX

Go


Go


Go


GO

Use cms_files_users

Go


Go


Go


Go


GO


GO

TroubleshootingIf you encounter the following error type Unable to drop user BBLEARN from database because user owns anobject in database during the execution of one of the above restore scripts, check and change ownership ofobjects. This error may be caused by either a table or stored procedure being owned by BBLEARN. Clients whohave updated from earlier builds may experience this problem. To correct this problem the administrator mustfind the stored procedure or table and change the ownership to dbo before the restore will run without errors.Ignoring the error will cause an unsuccessful database restore.

UNIX

About Backup and RecoveryThis topic offers some tips on system-wide backups and describes the tools in Blackboard Learn forincrementally backing up Courses andOrganizations.

System Backup and RecoveryAdministrators should backup the database and file system according to the needs of the Institution.Blackboard Learn supports full backup and restores at the operating system and database levels. As a generalrule, daily backups should be kept for two weeks, as errors may not appear for several days. Recovery plansshould include how to restore the entire system. For assistance restoring the system, contact BlackboardTechnical Support by logging in to Behind the Blackboard at https://behind.blackboard.com.

Incremental Data ProtectionBlackboard Learn includes the following utilities for incrementally backing up individual Courses andOrganizations:


9.1 S

P6 BETA D

RAFT



l Export/Import: Export takes Course content and puts it in a package that can be used in anotherCourse at a later date. One or more Course areas can be included in the package.

l Archive/Restore: The Archive Course function creates a record of the Course including userinteractions. It is most useful for recalling Student performance or interactions at a later time. Thearchive package is saved as a .ZIP file that can be restored to the system at another time.

The command line tool that processes batch operations for Export/Import and Archive/Restore is a powerfultool for backing up Course andOrganization data.

Note: The default size limit for content uploaded though the user interface is 250MB. When attempting toupload files larger than 250MB using the interface, users will receive an error. This limit does not apply toWebFolder uploads. To upload larger files, Administrators can upload the files using the command line or they canincrease the Tomcat default size setting. To increase themaximum upload limit, modify the parameter locatedin webapps/blackboard/WEB-INF/config/struts/reporting-struts-config.xml. The filesize upload limit is tied to Tomcat, therefore it is not encountered withWebDAV uploads. Because the settingis tied to Tomcat, the services must be restarted for the change to take effect.

Avoiding Recovery of Files During UpgradeDuring a Blackboard Learn upgrade, items such as custom folders, and archived snapshots which are storeddirectly beneath the blackboard_home directory aremoved to a time-stamped backup directory. Customizedfiles and folders that are not Blackboard-owned will be considered unexpected andmoved to the backupdirectory. To avoid your customized non-Blackboard-owned files from beingmoved during an upgrade, createclient-dirs.txt and client-files in your config directory. List each file and folder's relative path toyour blackboard_home directory on its own line in the respective text file. The files do not accept wildcards,so the files and folders must be specified individually. This methodmust be used with caution to avoid apartially upgraded environment, and if the file is Blackboard-owned and customized it will still be overwrittenwith the new version.

Resource PlanningVerify that the target databases have sufficient space before restoring Blackboard Learn and the contentmanagement data.

How to Check the Tablespace Sizes in the Source DatabaseExecute the following SQL query to determine the space used by Blackboard Learn in each tablespace:

Blackboard LearnSELECT tablespace_name, SUM (bytes) FROM dba_segments WHERE tablespace_name LIKE 'BB%'GROUP BY tablespace_name;

Example of Output for Blackboard LearnTABLESPACE_NAME SUM(BYTES)








9.1 S

P6 BETA D

RAFT


Content ManagementSELECT tablespace_name, SUM(bytes) FROM dba_segments WHERE tablespace_name LIKE 'CMS%'GROUP BY tablespace_name;

Example of Output for Content ManagementTABLESPACE_NAME SUM(BYTES)

CMS_DATA 3801088

CMS_DOC 87425024

CMS_INDX 1966080

How to Verify that the Corresponding Target Tablespaces Have SufficientSpaceThe following query can return two or more rows for each tablespace. Each row shows themaximum size ofeach file that belongs to that tablespace. If themaxbytes equals 0, themaximum is unlimited. Some operatingsystems limit the file size to 2GB. Therefore, Blackboard recommends limiting the file size to 2GB even thoughthe operating systemmay be capable of handling larger sizes.

To determine the total size of each tablespace, add all themaxbytes together. If themaxbytes of a tablespaceequals 0, substitute with 2GB before adding themaxbytes together. Execute the following SQL query todeterminemaximum space to which each tablespace can grow:

Blackboard LearnSELECT tablespace_name, maxbytes FROM dba_data_files WHERE tablespace_name LIKE 'BB%';

Example of Output for Blackboard LearnTABLESPACE_NAME MAXBYTES







Content ManagementSELECT tablespace_name, maxbytes FROM dba_data_files WHERE tablespace_name LIKE 'CMS%';

Example of output for Content ManagementTABLESPACE_NAME MAXBYTES

CMS_DATA 2097152000

CMS_INDX 2097152000

CMS_DOC 2097152000


9.1 S

P6 BETA D

RAFT


Insufficient Available SpaceIf themaximum available is not sufficient, there are two options available for increasing the space. Both optionsapply to Blackboard Learn and content management. The first option is to increase the file size (which isrecommended), and the second option is to add one or more files.

How to Increase the File SizeIf the required space in any tablespace is less than 2GB and themaximum available space is not sufficient, thesize of the file may be increased up to 2GB. For example, if BBLEARN_DATA tablespace requires 700MB, butthemaximum available space is only 500MB, increase the file size to 2GB. Before increasing the file size,locate the file name that belongs to the BBLEARN_DATA tablespace.

1. Locate the file name and note the file naming convention. The file naming convention should betablespace_name_filesequential_number.dbf , where the first sequential number is'1'.SELECT file_name FROM dba_data_files WHERE tablespace_name='BBLEARN_DATA';

2. Resize the file.ALTER DATABASE datafile 'path_to_file/bblearn_data_file1.dbf' RESIZE 2000M;

How to Add One or More FilesIf the required space in any tablespace is greater than 2GB and themaximum available space is not sufficient,one or more files must be added to increase the available space. For example, if BBLEARN_INDX tablespacerequires 5GB, but themaximum available space is only 2GB, another two files of 2GB eachmust be added toresult in a total of 6GB. Additional space which is not currently in use does not have a negative impact; and isrecommended for scaling. Use the following steps to add the files.

1. Find the existing file and its path:SELECT file_name FROM dba_data_files WHERE tablespace_name='BBLEARN_INDX';

2. Add two files to increase the available space:ALTER TABLESPACE BBLEARN_INDX ADD datafile 'path_to_file/bblearn_indx_file2.dbf' SIZE 2000M;


About Moving Blackboard Learn in an Oracle EnvironmentThis section explains how tomove Blackboard Learn and Content Collection files to another server.

Content Collection files are available only if your school licenses content management.

This information applies to all systems using a UNIX or Linux Operating System with anOracle® database. Tolearnmore about the technologies supported in Blackboard Learn, see theMaintenance Center.

There are several methods and solutions for Administrators interested in establishing regularly scheduledbackups (and associated restore procedures) of Oracle databases. Regularly scheduledmaintenance isoutside the scope of this document. To learnmore, see the documentation supplied by Oracle.

Working with Large DatabasesWhenworking with a large database, use the nohup utility for the export and import procedures. This willenable the processes to continue running even if the connection is lost. If the shell exits, the nohup utility will


9.1 S

P6 BETA D

RAFT




ignore the SIGHUP (signal hangup) thereby keeping the child processes from being terminated. The appropriatesyntax is as follows:

/usr/bin/nohup command [argument]

Processes run by /usr/bin/nohup are immune to SIGHUP and SIGQUIT (signal quit). The nohup utilitydoes not ignore SIGTERM (terminate signal). To locate nohup on the system, issue the command:

which nohup

In addition to using the nohup utility, the process may also be turned into a background process by appendingan “&” to the end of the string. Making a process a background process allows for the process to complete whilealso leaving the terminal available for additional use. The appropriate syntax is as follows:

/usr/bin/nohup command [argument] &

Moving Content Management Files

How to Move Files1. Login as bbuser to perform the following steps.2. Compress the Blackboard Learn and content management files (if applicable) on the source

application server using any compression option. As an example, a zipped tar ball is thecompression option.cd blackboard_home/content/vi/bblearn/

tar zcvf ls_courses_files.tgz *

cd blackboard_home/content/cmsdata

tar zcvf cmsdata_files.tgz *

3. Transfer ls_courses_files.tgz to the blackboard_home/content/vi/bblearndirectory on the target application server and cmsdata_files.tgz to blackboard_home/content

4. Decompress the Blackboard Learn and content management files (if applicable) on the targetapplication server using any decompression option.As an example, the files are unzipped anduntarred.cd blackboard_home/content/vi/bblearn

tar zxvf ls_courses_files.tgz

cd blackboard_home/content

tar zxvf cmsdata_files.tgz

Note: The content management directories must be backed up separately. When installing Blackboard Learn,the location of these directories can be changed.

Exporting the Database in an Oracle EnvironmentThe first step in moving the Blackboard Learn is to export the source databases. This must be done beforeexporting the content management databases.

Before exporting a database, place the source application server in maintenancemode and verify there is notany type of database activity. Backup and export both the file system, and the database during the samemaintenance session to avoid data corruption.


9.1 S

P6 BETA D

RAFT


How to Export the Blackboard Learn Databases1. Perform a schema level export for the databases using the system account and the information in

the following table.

DatabaseName Command Dump Name

bbadmin exp userid=system/manager owner=bbadmin buffer=2048000file=bbadmin.dmp consistent=y

bbadmin.dmp

bblearn exp userid=system/manager owner=bblearn buffer=2048000file=bblearn.dmp consistent=y

bblearn.dmp

bblearn_stats

exp userid=system/manager owner=bblearn_statsbuffer=2048000 file=bblearn_stats.dmp consistent=y

bblearn_stats.dmp

2. Compress the Blackboard Learn dump files on the source application server using anycompression option. For the purposes of this document, a zipped tar ball is the compression option.Compress the dump files as follows:tar zcvf bbadmin_export.tgz bbadmin.dmp

tar zcvf bblearn_export.tgz bblearn.dmp

tar zcvf bblearn_stats_export.tgz bblearn_stats.dmp

3. Transfer the compressed files to the target server using binary mode.

How to Export the Content Management Databases1. Perform a schema level export for the databases using the system account and the following table:

DatabaseName Command

DumpName

cms exp userid=system/manager owner=cms buffer=2048000file=cms.dmp consistent=y

cms.dmp

cms_doc exp userid=system/manager owner=cms_doc buffer=2048000file=cms_doc.dmp consistent=y

cms_doc.dmp

2. Compress the content management dump files on the source application server using anycompression option. For the purposes of this document, a zipped tar ball is the compression option.Compress the dump files as follows:tar zcvf cms_export.tgz cms.dmp

tar zcvf cms_doc_export.tgz cms_doc.dmp

3. Transfer the compressed files to the target server using binary mode.

Setting Up Target System for Import in an Oracle Environment

How to Set Up the Target System1. Verify that the target application server is accessible.2. Update the host names in /etc/hosts file on both the application and database servers. If this

step is not completed, the application server and database server will not properly communicate.3. Stop all Blackboard services with the following command:

./blackboard_home/tools/admin/ServiceController.sh services.stop


9.1 S

P6 BETA D

RAFT


4. Keep a record of the db_user passwords, and the statistics user for each BBUID (BlackboardUser ID). The passwords are required for the Database Import. Use the following SQL query toobtain the passwords from the bbadmin database:SELECT bbuid, db_user, db_pass, stat_db_pass FROM bb_instance;

5. Keep a record of the passwords for the following content management database users:l cms

l cms_doc

Importing the Database in an Oracle EnvironmentAfter the Blackboard Learn and content management export, the databases are ready to be imported into theOracle instance on the new database server. The Blackboard Learn databases must be imported before thecontent management databases.

Importing and Configuring the Blackboard Learn Databases

How to Import and Configure the bbadmin Database1. Login as system and drop the bbadmin user.

DROP USER bbadmin CASCADE;

ALTER TABLESPACE bbadmin_data COALESCE;

ALTER TABLESPACE bbadmin_indx COALESCE;

2. Login as system and re-create user bbadmin, the correct passwordmust replace bbpassword.CREATE USER bbadmin IDENTIFIED BY "bbpassword" DEFAULT TABLESPACE bbadmin_dataTEMPORARY TABLESPACE temp QUOTA UNLIMITED ON bbadmin_data QUOTA UNLIMITED ONbbadmin_indx;

GRANT connect, resource TO bbadmin;

GRANT alter user TO bbadmin;

GRANT select any table TO bbadmin;

GRANT analyze any TO bbadmin;

GRANT drop any table TO bbadmin;

GRANT query rewrite TO bbadmin;

GRANT alter tablespace TO bbadmin;

GRANT create sequence TO bbadmin;

3. Unzip and import the bbadmin schema.imp system/manager file=bbadmin.dmp fromuser=bbadmin touser=bbadmin commit=Ybuffer=2048000

4. Update the db_host, db_pass, stat_db_host, and stat_db_pass for each BBUID. Thefirst BBUID is called bblearn by default. If the port numbers are different, thesemust also beupdated. Replace NEW_PASSWORD with the password that was documented in Setting Up TargetSystem for Import in anOracle Environment.UPDATE bb_instance SET db_host = 'NEW_DB_HOST_NAME', db_pass = 'NEW_PASSWORD ',db_instance = 'NEW_ORACLE_SID', stat_db_host = 'NEW_STAT_DB_HOST_NAME', stat_db_pass = 'NEW_STAT_DB_PASSWORD' where bbuid = 'bblearn';

COMMIT;


9.1 S

P6 BETA D

RAFT


How to Import and Configure the bblearn_stats Database1. Login as system and drop the bblearn_stats user:

DROP USER bblearn_stats CASCADE;

ALTER TABLESPACE bblearn_stats_data COALESCE;

ALTER TABLESPACE bblearn_stats_indx COALESCE;

2. Login as system and re-create user bblearn_stats, the correct passwordmust replacebbpassword.CREATE USER bblearn_stats IDENTIFIED BY "bbpasswd" DEFAULT TABLESPACE bblearn_stats_data TEMPORARY TABLESPACE temp QUOTA UNLIMITED ON bblearn_stats_dataQUOTA UNLIMITED ON bblearn_stats_indx;

GRANT connect, resource to bblearn_stats;

GRANT alter user TO bblearn_stats;

GRANT select any table TO bblearn_stats;

GRANT analyze any TO bblearn_stats;

GRANT drop any table TO bblearn_stats;

GRANT query rewrite TO bblearn_stats;

GRANT alter tablespace TO bblearn_stats;

GRANT create sequence TO bblearn_stats;

3. Import the bblearn_stats schema.imp system/manager file=bblearn_stats.dmp fromuser=bblearn_statstouser=bblearn_stats commit=Y buffer=2048000

How to Import and Configure the bblearn Database1. Login as system and drop the bblearn user.

DROP USER bblearn CASCADE;

ALTER TABLESPACE bblearn_data COALESCE;

ALTER TABLESPACE bblearn_indx COALESCE;

2. Login as system and re-create user bblearn, the correct passwordmust replace bbpassword.CREATE USER bblearn identified BY "bbpasswd" DEFAULT TABLESPACE bblearn_dataTEMPORARY TABLESPACE temp QUOTA UNLIMITED ON bblearn_data QUOTA UNLIMITED ONbblearn_indx;

GRANT connect, resource to bblearn;

GRANT alter user TO bblearn;

GRANT select any table TO bblearn;

GRANT analyze any TO bblearn;

GRANT drop any table TO bblearn;

GRANT query rewrite TO bblearn;

GRANT alter tablespace TO bblearn;

GRANT create sequence TO bblearn;

3. Import the bblearn schema:imp system/manager file=bblearn.dmp fromuser=bblearn touser=bblearn commit=Ybuffer=2048000

4. Connect as bblearn and perform the following grants.GRANT select on users TO bblearn_stats;

GRANT select on course_main TO bblearn_stats;


9.1 S

P6 BETA D

RAFT


GRANT select on cartridge TO bblearn_stats;

GRANT select on course_users TO bblearn_stats;

GRANT select on system_tracking TO bblearn_stats;

GRANT select on activity_accumulator TO bblearn_stats;

TroubleshootingIf the error message, ORA-00001: unique constraint (SYS.I_JOB_JOB) violated appears, loginas bbadmin, bblearn,or bblearn_stats depending on which database encountered the error, and runthe following command to resubmit the job.

VARIABLE jobnum1 NUMBER;

BEGIN

DBMS_JOB.SUBMIT(

:jobnum1,

'analyze_my.bbtabs;',

SYSDATE,

'TRUNC(SYSDATE)+26/24'

);

COMMIT;

END;

/

Importing and Configuring the Content Management Databases

How to Import and Configure the cms Main Database1. Login as system and drop the cms user:

DROP USER cms CASCADE;

ALTER TABLESPACE cms_data COALESCE;

ALTER TABLESPACE cms_indx COALESCE;

2. Login as system and re-create user cms, the correct passwordmust replace bbpassword.CREATE USER cms IDENTIFIED BY "bbpasswd" DEFAULT TABLESPACE cms_data TEMPORARYTABLESPACE temp QUOTA UNLIMITED ON cms_data QUOTA UNLIMITED ON cms_indx;

GRANT connect, resource to cms;

GRANT alter user TO cms;

GRANT select any table TO cms;

GRANT analyze any TO cms;

GRANT drop any table TO cms;

GRANT query rewrite TO cms;

GRANT alter tablespace TO cms;

GRANT create sequence TO cms;

3. Import the cms schema.imp system/manager file=cms.dmp fromuser=cms touser=cms commit=Y buffer=2048000


9.1 S

P6 BETA D

RAFT


How to Import and Configure the cms_doc Database1. Login as system and drop the cms_doc user:

DROP USER cms_doc CASCADE;

ALTER TABLESPACE cms_doc_data COALESCE;

ALTER TABLESPACE cms_doc_indx COALESCE;

2. Login as system and re-create user cms_doc, the correct passwordmust replace bbpassword.CREATE USER cms_doc IDENTIFIED BY "bbpassword" DEFAULT TABLESPACE cms_doc_dataTEMPORARY TABLESPACE temp QUOTA UNLIMITED ON cms_doc_data QUOTA UNLIMITED ONcms_doc_indx;

GRANT connect, resource to cms_doc;

GRANT alter user TO cms_doc;

GRANT select any table TO cms_doc;

GRANT analyze any TO cms_doc;

GRANT drop any table TO cms_doc;

GRANT query rewrite TO cms_doc;

GRANT alter tablespace TO cms_doc;

GRANT create sequence TO cms_doc;

3. Import the cms_doc schema.imp system/manager file=cms_doc.dmp fromuser=cms_doc touser=cms_doc commit=Ybuffer=2048000

4. The following will grant two privileges that are required to install Blackboard onOracle:SQL> @$ORACLE_HOME/rdbms/admin/rstrconn.sql

SQL> commit;

SQL> exit

If any errors appear during the database import, contact Blackboard Client Support. Provide them with theterminal output along with database version information, operating system information, and environmentsettings.

Editing the Properties File in an Oracle EnvironmentAs part of the database restoration, administrators must edit the blackboard_home/config/bb-config.properties file for Blackboard Learn and if appropriate, the blackboard_home/apps/bbcms/config/bbcms-install.properties file for content management. The followingis a list of properties to review after restoring the databases.

Blackboard Learn

Database Configuration – Generic:l bbconfig.database.bbadmin.machine.machinename=lion

l bbconfig.database.bbadmin.machine.fullhostname=lion.mydomain.com

l bbconfig.database.bbadmin.machine.instancename=bb91

l bbconfig.database.bbadmin.machine.systemuserpassword=oraclepassword

l bbconfig.database.bbadmin.db.password=bbadminpassword


9.1 S

P6 BETA D

RAFT


Database Configuration – Oracle:l bbconfig.database.bbadmin.db.oracle.indexdir=/usr/local/oracle/bb/log2

l antargs.default.vi.db.password=password

l antargs.default.vi.stats.db.password=password

l antargs.default.vi.report.user.password=password

l bbconfig.bbmaster.database.password=mypassword

Platform Configuration – Unixl bbconfig.unix.sendmail.path=/usr/lib/sendmail

l jvm configuration – java bound processes

l bbconfig.database.machinename=cougar

l bbconfig.database.fullhostname=cougar.mydomain.com

l bbconfig.mssql.data.dir=/usr/local/oracle/bb/log2

Main Application Configuration - Generic:l bbconfig.java.home=/usr/local/jdk1.6.0

l bbconfig.webserver.fullhostname=cougar.mydomain.com

l bbconfig.appserver.fullhostname=cougar.mydomain.com

l bbconfig.appserver.machinename=cougar

l bbconfig.collabserver.fullhostname.default=cougar.mydomain.com

Content Managementl xythos.license.key=OEM-BLACKBOARD-XXXX

l cms.db.cms-user.pass=password

Note: These properties are application server specific and will only change if a restore of the application isbeing completed.

If the above values are updated, the new values do not take effect until they are pushed through the system. Topush the changes, log in as ‘root’ on the application server machine and run the following scripts:


blackboard_home/apps/bbcms/bin/push-cs-config-update.sh


PushConfigUpdates.shmust be run both before and after running the push-cs-config-update.shscript. The PushConfigUpdates.sh script will automatically update the admin data in the database byreading the value in the config.xml file. The changes to the database hostname and port, instance name,and externally visible webserver hostnamewill be pushed to the database. To learnmore, seePushConfigUpdates.


9.1 S

P6 BETA D

RAFT

Performance Optimization > About Optimizing Blackboard Learn

Performance Optimization

About Optimizing Blackboard LearnBlackboard Learn has a three-tiered architecture consisting of a web server, an application server, and arelational database.

Blackboard Learn Architecture

Note: For current information about supported configurations, go to the BlackboardMaintenance Center bylogging into Behind the Blackboard (https://behind.blackboard.com).

Characteristics of the Blackboard Learn application architecture and its flexible deployment options enableclients to scale and optimize the performance and responsiveness of their Blackboard Learn deployment in theirparticular environment:

l Distributed Processing Load: The Blackboard Learn processingmodel, which is based onWeb 2.0and client-rich technologies, distributes the load between the client-side browser, the application, andthe database. This reduces the perceived response time for users because they can interact with thepage as it loads elements asynchronously.

l Server-Side Caching: The Blackboard Learn server-side caching architecture uses Ehcache in anumber of areas to reduce the number of time-consuming trips to the database to fulfill requests fordata that does not change during the course of a user's session. Ehcache is a pure Java™, in-process cache that is designed for large, high concurrency systems. Each of these cachingstructures is configured within the bb-config.properties file and can be configured on a case-by-case basis.


9.1 S

P6 BETA D

RAFT




Performance Optimization > Optimizing Performance

l Flexible Deployment Options: The Blackboard Learn architecture supports maximum scalabilityand high service levels by providing a variety of deployment options, including load-balancing,application tier clustering, and virtualization. Although Blackboard Learn can be deployed in atraditional horizontal manner, it also can be clustered at the application tier to load balance from theweb server to multiple JVMs, or virtualized to runmultiple instances of Blackboard Learn and the webserver on virtualized servers. Tomake the best use of available hardware resources, BlackboardLearn can be deployed using any or a combination of two or three of these options.

For information about the recommended architecture for aWindows environment, see theWhite PaperOptimizing Blackboard Academic Suite [Blackboard Learn] on Dell Servers and Storage: Taking Advantage ofVirtualized Resources.

Although the Blackboard Learn architecture and the selected deployment option help users experienceimproved performance, overall system performance can be further improved by optimizing the various systemcomponents.

Optimizing PerformanceAll application environments are different. Although the out-of-the-box configuration of any application cansatisfy basic processing needs, extended uptime with fewer maintenance windows, increased numbers ofusers, and usage patterns can result in performance issues. To configure the system appropriately, firstevaluate the specific environment and application usage.

Although scaling the Blackboard Learn deployment supports an increased number of users without adverselyaffecting performance, system performance can be further improved to achieve higher service levels, reducerisk, and improve user perceptions of performance, which will in turn increase user satisfaction and reduce userabandonment. To do so, optimize the performance of the components in the application tier as well as theperformance of the database.

In general, Release 9.1 is more responsive and scalable than both Release 9.0 Service Pack 3 and Release 8Service Pack 6 across all supported platform configurations. Blackboard completedmore than 2000 hours ofperformance tests on Release 9.1, and this number will continue to increase as Blackboard produces ServicePacks against the Release 9.1 code line.

Optimizing Application Tier PerformanceTo achieve the best performance in the application tier, optimize each of these components.

l Web server: The primary purpose of the web server in the Blackboard Learn architecture is to proxydynamic business logic and static content requests to the Tomcat application container over HTTP orsecure HTTPS. In Blackboard Learn, the web server used depends on the operating systemenvironment. In aMicrosoft® Windows® environment, the web server is Microsoft InternetInformation Server (IIS). In a UNIX® environment, the web server is Apache™HTTP Server. Tolearnmore, see Configuring Apache HTTP Server or ConfiguringMicrosoft IIS.

l Application container: Apache™Tomcat is an open-source Java application container that ispackaged with Blackboard Learn for all operating systems. To effectively optimize Tomcatperformance, it is necessary to understand the role of the Java Virtual Machine (JVM™) andcontainer components, such as execution threads and JDBC connections. To learnmore, see UsingTomcat Clusters.

Note: The web server and the application container must reside on the same server.

l Java Virtual Machine (JVM™): The Java 2 Platform, Standard Edition (J2SE™) JVM is themostcritical component of the Java platform because it manages memory allocation and controls how thecontainer handles incoming requests. If the system has been deployed using application tier


9.1 S

P6 BETA D

RAFT



















Performance Optimization > Apache

clustering, the application tier might includemultiple servers or JVMs that need to be optimized. Tolearnmore, see Using Tomcat Clusters.

Optimizing Database Tier PerformanceIn Blackboard Learn, the database used depends on the operating system environment. In aWindowsenvironment, the databasemust beMicrosoft SQL Server®. In a UNIX environment, the databasemust beOracle®. To learnmore, see Pre-Installation Recommendations in a SQL Environment or Pre-InstallationRecommendations in anOracle Environment.

Note: Although Blackboard provides general optimization information, a particular environment might benefitfrom different settings.

Optimizing Addressable Memory Using 64-Bit DeploymentsBlackboard Learn Release 9.1 is the first release to offer an entire application and database footprint using 64-bit addressablememory. To take advantage or more addressablememory, Blackboard strongly encouragesclients to deploy using 64-bit operating systems (OSs) and sub components (Java and SQL Server or Oracle).As part of the 64-bit deployment, Blackboard encourages clients to take advantage of larger Java VirtualMachines (JVMs) that range from 2GB to 16GB in size. The preferred size is 4GB, but performance testing hasbeen conducted with acceptable performance as high as 16GB.

Apache

Configuring Apache HTTP ServerApache HTTP Server configuration is managed using parameters in the bb-config.properties file. In turn, the scripts within Blackboard Learn (processed by the PushConfigUpdates command) update theappropriate Apache files.

For steps to edit the bb-config.properties file, see bb-config.properties File.

The following table describes each parameter and its recommended setting.

Parameter Name DescriptionRecommendedSetting

bbconfig.unix.httpd. minspareservers Dynamic mechanism for keeping a minimum number ofspare servers available to handle simultaneous requestsfrom a browser

5

bbconfig.unix.httpd.maxspareservers Dynamic mechanism for keeping a maximum number ofspare servers available to handle simultaneous requestsfrom a browser

50

bbconfig.unix.httpd.startservers Number of servers to start initially 10


9.1 S

P6 BETA D

RAFT



bbconfig.unix.httpd.maxclients Maximum number of servers allowed to be runningThis limits the number of clients that can connect at thesame time. Blackboard Learn is compiled to support asmany as 5,000 clients.The value for this parameter must always be higher thanthe value for bbconfig.appserver.maxthreads to avoidkeepalive issues. To learn more, see Configuring DatabaseConnections.

Note: For Tomcat cluster configurations, Apache HTTPServer acts as the main load-balancing component. Asmore instances of Tomcat are deployed, increase this valuefor each instance in the cluster.

400-1024

bbconfig.unix.httpd.maxrequestsperchild Number of requests each child process is allowed toprocess before the child dies

Note: Setting this parameter to a higher value reducesdelays that are caused by spawning new Apache HTTPDchild processes. Prolonged use is not an issue forBlackboard Learn.

1024-2048

bbconfig.unix.httpd.keepalivetimeout Number of seconds to wait for the next request from thesame client on the same connection

15

bbconfig.unix.httpd.keepalive Whether to allow persistent connections (more than onerequest per connection)

On

bbconfig.unix.httpd.MaxKeepAliveRequests Maximum number of requests to allow during a persistentconnection

100

Using the Server-Status Module for ApacheNote: For security reasons, Blackboard recommends that Server-Status be enabled only if the user is familiarwith themodule and understands how to deny access to unwanted users.

The Apache Server-Status module provides an instrumentation tool set to determine how well the Apacheserver instance is performing. Server-Status provides the following information about an Apache serverinstance:

l The number of children serving requests.l The number of idle children.l The status of each child, the number of requests that child has performed, and the total number of

bytes served by the child.l The total number of accesses and byte count served.l The time the server was started or restarted and the amount of time the server has been running.l An average of the number of requests per second, the number of bytes served per second, and the

average number of bytes per request.l The current percentage of the CPU used by each child and in total by Apache.l The current hosts and requests being processed.


9.1 S

P6 BETA D

RAFT


How to Temporarily Enable Server-Status1. Open the httpd.conf file in the following directory:

%/usr/local/blackboard_directory/apps/httpd/conf

2. Uncomment the ExtendedStatus On line by removing the pound sign (#) at the beginning of theline:#ExtendedStatus On

For example:

ExtendedStatus On

3. Locate the <Location> section of code. If it does not exist, add the code to the end of the file:#<Location /server-status>

# SetHandler server-status

# Order allow, deny

# Allow from all

# Deny from all

#</Location>

4. Uncomment the <Location>, SetHandler and </Location> lines as well as the appropriateaccess control lines to allow server status reports by removing the pound signs (#) at the beginningof each line:

For example:

<Location /server-status>

SetHandler server-status

Order allow, deny

Allow from all

#Deny from all

</Location>

5. Save and close the file.6. Restart the Apache web server using the following two commands in order:

./ServiceController.sh services.webserver.stop

./ServiceController.sh services.webserver.start

7. View the Server-Status page in a web browser by going to the following URL:http://webServerName/server-status.

Note: The httpd.conf file will be overwritten each time the PushConfigUpdates command isrun. Tomake the server-status URL permanent, repeat these steps for the template filehttpd.conf.bb.

Measuring Interface PerformanceSystem performance can be defined as service time plus latency. When interfaces begin to queue requests,latency occurs until the bottleneck no longer exists. Blackboard recommends measuring the state of theinterfaces on a regular basis using an instrumentation tool set such as Server-Status, or predefiningmeasurements using a tool such as ApacheBench (Ab).


9.1 S

P6 BETA D

RAFT

Performance Optimization > IIS

Taking crudemeasurements at an operating system level using tools such as NetStat can provide similardetails. In addition, Quest® Foglight™, specifically their ApacheWeb Server cartridge, can provide historicalmetrics for the web server interfaces.

IIS

Configuring Microsoft IISWhen using Blackboard Learn in aWindows environment, Microsoft IIS manages the HTTP and HTTPSrequests to and replies from the Tomcat container.

Note: Blackboard Learn does not ship with Microsoft IIS. To learnmore about IIS, see http://www.iis.net.

Tomake changes to the IIS configuration, edit the parameters in the bb-config.properties file and thenrun the WebsiteReinstall.bat script in the following directory:

blackboard_directory\tools\admin




bbconfig.webserver.keepalive Whether to allow persistent connections (more than onerequest per connection) Always make sure to review thesetting with your hardware load balancer vendor.

1

bbconfig.webserver.keepalivetimeout Number of seconds to wait for the next request from the sameclient on the same connection

15

bbconfig.webserver.compression Enables HTTP Compression via GZip Yes

The number of connections to IIS is set by default to unlimited. Although this setting can be changed using theInternet Information Services (IIS) Manager, Blackboard recommends not changing it. Controlling the numberof connections to IIS becomes important only when themanagement of resource consumption is the toppriority.

HTTP CompressionEnable GZip compression through the bb-config.properties file by toggling it on or off. Both IIS andApache support GZip as a native compression ability.

Enabling Dynamic CompressionVerify this setting in IIS 6.0 by visiting Configure Compression in IIS 6.0 usingWindows 2003 or in IIS 7.0 byvisiting Configure Compression in IIS 7.0 usingWindows 2008.

Monitoring Performance CountersIIS contains built-in performance counters that can be accessed using any tool or framework that is capable ofaccessingWindows Performance Counters. Themost commonly used tool is Perfmon.

Certain performance counters are worth monitoring for a greater understanding of how IIS contributes to theoverall scalability of Blackboard Learn. Themost likely issue to emerge is IIS processes being unable toacquire a lock on additional memory.


9.1 S

P6 BETA D

RAFT

http://www.iis.net/

















Performance Optimization > Tomcat

The following list includes the key data counters to observe:l Memory\Pages per second

l Memory\Available Bytes

l Memory\Committed Bytes

l Processor% Processor Time

l Process (W3WP) Thread Count

l Thread (W3wp:Thread #)% Processor Time

Monitoring ThreadsThe following list includes the key points to remember whenmonitoring threads:

l If the web server is running in worker process isolationmode, monitor theW3wp instance.l It can be difficult to balance the number of threads against overall performance as measured by

connections and requests. When tuning threads, follow up with overall performancemonitoring to seewhether performance increases or decreases.

l Chart the Process\Thread Count: W3wp value over time to see how many threads the workerprocess creates and how the number of threads varies. Then observe the processor time for eachthread in the process (Thread% Processor Time: W3wp/Thread #) during periods of high,medium, and low server activity (as indicated by the other performancemeasures).

l To determine whether the thread count needs to be adjusted, compare the number of threads and theprocessor time for each thread in the process to the total processor time. If the threads are constantlybusy, but are not fully using the processor time, performancemight be improved by allowingmorethreads. However, if all of the threads are busy and the processors are operating at close to theirmaximum capacity, it is best to distribute the load across more servers instead of increasing thenumber of threads.

For detailed information about monitoring threads in IIS, seehttp://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/a63ee1c2-04d6-44dc-b4d6-678eb3117bf9.mspx.

Throttling Connection SizesAvoid limiting connection capability by throttling connection sizes. The number of connections to IIS is set bydefault to unlimited, so ideally an unlimited number of connections can bemade to IIS and then passed toTomcat without issue. Although this setting can be changed using the Internet Information Services (IIS)Manager, Blackboard recommends not changing it. Controlling the number of connections to IIS becomesimportant only when themanagement of resource consumption is the top priority.

Tomcat

Using Tomcat ClustersTomcat Application Clusters consist of multiple Blackboard Learn java application (JVM) server instancesrunning simultaneously (on the same physical server) and working together to provide increased scalability.Scalability is an application's ability to support a growing number of users. If it takes one application 10milliseconds to respond to one request, how long does it take to respond to 10,000 requests? If a user logs on at3 AM do they experience the same responsiveness as they do at 3 PM? Tomcat Application Clusters ensure


9.1 S

P6 BETA D

RAFT

http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/a63ee1c2-04d6-44dc-b4d6-678eb3117bf9.mspx






that Blackboard Learn remains responsive by adding server instances to a cluster without interruption ofservice.

Note: Cluster nodes cannot bemodified. If a change is required, the nodemust be removed and then addedagain with the updated information.

Tomcat Application Clusters are not meant as a replacement for traditional load balance configurations, but asa complementary scheme that provides improved scalability and failover capabilities. Traditional load-balancingis a physical distribution of server instances across multiple servers. Tomcat Application Clusters are logicalinstances of the Java application components that reside on a single server, or are distributed across multipleservers.

There are two types of server clustering: horizontal and vertical:

l Horizontal clustering allows server instances to be deployed across multiple physical servers. Thismethod of clustering is not implemented by Blackboard because Blackboard already supports load-balancing.

l Vertical clusters, also known as multi-home clusters, allow multiple server instances to be run on asingle machine. This method takes full advantage of the processing power of a single server. Verticalclusters are load-balanced by the web server.

Tomcat Clustering runs on all Blackboard platforms (Windows, Linux, and Solaris).

Configuring Database ConnectionsEstablishing a connection from the application container to the database server is time consuming. As a result,JDBC connection pooling is widely used in Blackboard Learn.

Blackboard Learn has multiple schemas that are used for a variety of functions. The core schema is BBLEARN(legacy: BB_BB60), which is where the bulk of key database objects and access reside. The BBLEARN_ADMIN schema is an administrative schema accessed by the start-up utilities and some administrativefunctions. The BBLEARN_STATS (legacy: BB_BB60_STATS) schema is an operational data store that isused for reporting to ease demand on BBLEARN (legacy: BB_BB60). BBLEARN_STATS (legacy: BB_BB60_STATS) is not accessible using the Blackboard Learn User Interface (UI).

Connections from the Apache Tomcat to the database aremanaged using parameters in the bb-config.properties file.

Note: This section provides recommended settings for the four key bbconfig.database parameters.




bbconfig.appserver.minthreads Minimum number of threads created for Tomcat 100

bbconfig.appserve.maxthreads Maximum number of threads allocated to Tomcat for32-bit 1.4 GB RAM in the heapspaceThis setting limits the number of requests that can besimultaneously processed by Tomcat.This parameter must be set lower than the value forthe bbconfig.unix.httpd.maxclients setting forApache on UNIX platforms.To learn more, see Sizing the Maximum ThreadCount.

200-250


9.1 S

P6 BETA D

RAFT



bbconfig.appserve.maxthreads Maximum number of threads allocated to Tomcat for64-bit 4 GB RAM in the heapspaceThis setting limits the number of requests that can besimultaneously processed by Tomcat.This number should match thebbconfig.unix.httpd.maxclients setting forApache on UNIX platforms.To learn more, seeSizing the Maximum ThreadCount.

400-800

bbconfig.min.heapsize.tomcat Minimum heap size allocated to the Tomcat JVM 1/2 of or equalto max.heapsize.tomcat

bbconfig.max.heapsize.tomcat Maximum heap size allocated to the Tomcat JVM for32-bit configurations.

1024-1400m

bbconfig.max.permsize.tomcat Maximum perm space allocated to the Tomcat JVM 320m

bbconfig.max.stacksize.tomcat Stack size for each thread in the Tomcat JVM 170-300k

bbconfig.jvm.options.extra.tomcat Additional settings used to configure the JVMTo learn more, see Using Non-Standard (-XX) JVMArguments.

User defined

bbconfig.database.instance.maxpoolsize Maximum number of connections waiting to servedatabase requests

The BBLEARN (legacy: BB_BB60) connection pool isthe primary database connection pool interface forthe Blackboard schema in Tomcat. Blackboardrecommends that this value be sized conservativelybased on need and usage. Start with a maximumvalue of 100, and then increase the maximum size asthe Tomcat application threads increase.

Optimally, this value should be equal to, but notgreater than, thebbconfig.appserver.maxthreads parametersetting.

Note: JDBC connection consumption is a symptomof a performance issue or degradation. Increasing theJDBC connection count will not always solve aperformance issue. Performance issues should bediagnosed by identifying bottlenecks at their source.

300-1024

bbconfig.database.instance.minpoolsize Number of connections waiting to serve databaserequests

10

bbconfig.database.instance.mssql.initpoolsize Initial number of connections waiting to servedatabase requests for SQL Server

10

bbconfig.database.instance.timeout Time window in which database transactions must beprocessed before a timeout occurs

60-300

Sizing the Maximum Thread CountSizing the bbconfig.appserver.maxthreads parameter is different for every Blackboard Learndeployment because the proper setting depends on application usage.


9.1 S

P6 BETA D

RAFT


Before changing this parameter value, make sure to understand system usage needs versus the resourcecapacity of CPU andMemory because both are factors. A one-to-one correlation between application threadsand system users does not exist. Tomcat uses a thread pool to manage a volume of user transactions. Mostcomponents in Blackboard Learnmake single thread requests, and some transactions require two or morethreads. These types of transactions are not multi-threaded, but rather they require multiple independentrequests such as a frameset. Thread requests typically occur in less than one second.

Thread consumption is a symptom of a performance issue or degradation. Increasing the thread count will notalways solve a performance issue. Performance issues should be diagnosed by identifying bottlenecks at theirsource.

Blackboard recommends setting the value based on need during peak usage time. Start with a relativelyconservative value, such as the default value of 200. Monitor thread usage using operating system tools (suchas Windows Task Manager, Prstat, NetStat, or Top) or third-party tools (such as Quest Foglight or Sun™JConsole), and then increase the thread count in increments of 25 to 50 as threads become saturated or used.

Note: When running on UNIX, make sure that themaximum thread count value is less than thebbconfig.unix.httpd.maxclients parameter value in the bb-config.properties file. To learnmore, seeConfiguring Apache HTTP Server.

Enabling HTTP CompressionEnable GZip compression through the bb-config.properties file by changingbbconfig.webserver.compression to yes. Both IIS and Apache support GZip as a native compressionability.

Sizing the Java Object HeapThe JavaObject Heap (Java Heap) stores Java objects, including instances of classes and the data that theobjects contain, such as primitives and references. The amount of memory allocated to the JVM as a wholeand to its individual regions is different for every Blackboard Learn deployment. As with themaximum threadcount value for Tomcat, the appropriate size of the Java Heap will vary depending on application usage.

Each JVM has built-in flags such as -verbosegc and -Xloggc that can be used to determine actual memoryusage. If using verbosegc, the access requests to both Apache and Tomcat will be logged, and as such istypically used to diagnose performance or stability issues. Memory consumption can bemonitored usingoperating system tools, such as Windows Task Manager, Prstat, NetStat, or Top, or third-party tools, such asQuest Foglight or Sun™ JConsole.

On 32-bit deployments, Blackboard recommends initially sizing the Java Heap to a value as close to 1.7GBthat the JVM will permit with start-up. Allocating smaller amounts of memory is very fast because there is noneed to search for freememory segments in the RAM. If properly managed, amemory allocation of 1.7 GBshould be sufficient for 32-bit JVMs. If thememory resources of a JVM with an allocation less than 1.7 GBbecome saturated or are consumed, increase thememory allocation in increments of 125 to 256 MB. If thememory resources continue to become saturated or are consumed, consider adding additional JVMs asdiscussed in the previous section. Additional non-standard HotSpot options can also be applied to improveoverall memory throughput andmanagement. To learnmore about the JVM options supported by Java, seehttp://java.sun.com/javase/technologies/hotspot/vmoptions.jsp.

Note: For 32-bit operating systems, Windows and Linux versions of the Sun JVM cannot be sized greater than1.7 GB.

On 64-bit deployments, Blackboard recommends initially sizing the Java Heap to a value between 2GB and4GB. Some customers have deployed substantially larger JVMs then 4GB with success. If thememoryresources of a JVM with an allocation less than 1.7 GB become saturated or are consumed, increase thememory allocation in increments of 500MB to 1 GB. If thememory resources continue to become saturated orbe consumed, consider adding additional JVMs as discussed in the previous section. Additional non-standard


9.1 S

P6 BETA D

RAFT

http://java.sun.com/javase/technologies/hotspot/vmoptions.jsp


HotSpot options can also be applied to improve overall memory throughput andmanagement. To learnmoreabout the JVM options supported by Java, seehttp://java.sun.com/javase/technologies/hotspot/vmoptions.jsp.

Using Non-Standard (-XX) JVM ArgumentsThe Sun Java Virtual Machine contains non-standard HotSpot VM options that are used to improve virtualmachine behavior, performance, and debugging. Non-standard options are prefixed with –XX.

Many non-standard options are available that can provide greater throughput and reduce overall latency. Usetuning exercises to determine which options are best suited for the conditions in your production environment.Use different logging options to provide insight into the value of each option. Given the variety of options andthe chance that these options may change from release to release, Blackboard recommends testing them inyour environments based on the output found in the garbage collections logs.

Note: Some of these options are platform-specific and will not work across all certified Blackboard operatingsystem platforms. In addition, these options can change across releases and patches, so pay close attentionwhen using them.

The following table describes the options that will provide that majority of the performance gain.

JVM Option Description

-XX:+UseConcMarkSweepGC

The concurrent collector is used to collect the tenured generation and does most of thecollection concurrently with the execution of the application. The application is pausedfor short periods during the collection.

-XX:+UseParNewGC This is used in conjunction with the concurrent collector on multiprocessor machines toenable young generation collection.

-XX:ParallelGCThreads This option should be set to the number of available CPUs for concurrent garbagecollection. This option is to be used in conjunction with -XX:+UseParNewGC.

-XX:NewRatio This option sets the size ratio between young and old generational spaces. This istypically set to a value between 2 and 4 depending on garbage collection patterns.

-XX:NewSize, -XX:MaxNewSize

This option sets the explicit size for the young generation space. This parameterrequires explicit sizes, and is recommended in place of the -XX:NewRatio parameterfor resizing the new generation space of the JVM.

To learnmore about the JVM options supported by Java, seehttp://java.sun.com/javase/technologies/hotspot/vmoptions.jsp.

Understanding the Regions of the Java HeapThe Java Heap consists of three regions:

l New/Young Region: This region is where all new objects are created. This region is divided intothree sub-spaces: Eden, Survivor 0, and Survivor 1. This region has the ability to dynamically resizeits virtual space.

l Old/Tenured Region: This region is where objects are placed when the New region overflows or anobject is tenured because it has an extended life. Objects can be removed from theOld region duringa full garbage collection.

l Permanent Region: This region holds the JVM’s class andmethod objects and often remainsunchanged. It is also where objects are placed when the New region overflows.


9.1 S

P6 BETA D

RAFT




Configuring EhcacheA cache is a collection of temporary data that either duplicates data located elsewhere or is the result of acomputation. Ehcache is a widely used Java-distributed cache for general purpose caching, Java EE™, andlight-weight containers.

Ehcache was introduced in Blackboard Learn Release 9.0 as a unified caching architecture. After the data is inthe cache, it can be accessed repeatedly at little cost by avoiding calls to the database.

Setting the cache-settings.properties Parameters

How to Edit the cache-settings.properties File1. Open the cache-settings.properties file in the following directory:

l UNIX:%/usr/local/blackboard_directory/config

l Windows:C:\blackboard_directory\config

2. Edit the parameters using the information in the following table, which describes each parameter.

Parameter Name Description

maxElementsInMemory(elements)

Maximum number of objects that will be created in memory

eternal Whether elements are eternalIf true, timeouts will be ignored and the element will never expire.

timeToIdleSeconds Maximum amount of time between accesses before an element expires

timeToLiveSeconds Maximum amount of time between creation and expiration before anelement expires

overflowToDisk Whether elements can overflow to disk when the memory store hasreached the maxInMemory parameter limit

evictionPolicy Policy to be enforced when the maxElementsInMemory parameter limit isreachedThe default policy is Least Recently Used (specified as LRU).

3. Save and close the file.4. Update the configuration by running the PushConfigUpdates command:

l UNIX:%/usr/local/blackboard_directory/tools/admin/ PushConfigUpdates.sh

l Windows:C:\blackboard_directory\tools\admin\PushConfigUpdates.bat

Understanding the bbconfig.cache ParametersThe bbconfig.cache parameters in the bb-config.properties file control how particular actionsperformed in Blackboard Learn use Ehcache. Blackboard does not recommend changing any of the defaultvalues for these parameters.


9.1 S

P6 BETA D

RAFT


The following table lists each Blackboard Learn cache, the specific bbconfig.cache parameters that controleach cache, and the actions users perform in Blackboard Learn that rely on the cache and its parameters. Ifextensive testing shows that these parameters should be changed for a particular environment, do so at yourown risk.

Cache Name Parameter Section Actions Using Parameter Settings

Blog Entries bbconfig.cache.courseBlogEntry Enter blog view pageDelete entryPost entryEdit entryAdd comments

Blog Indexes bbconfig.cache.courseBlogIndexesCache Enter blog view pageDelete entryPost entryEdit entry

Blog EntryComments

bbconfig.cache.courseBlogEntryComments Enter blog view pageDelete entryPost entryEdit entryEnter comments

Blog EntryComment Dates

bbconfig.cache.courseBlogCommentDates Enter blog view pageDelete entryPost entryEdit entryEnter comments

Blog Contributors bbconfig.cache.courseBlogContributors Enter blog view pageDelete entryPost entryEdit entryEnter commentsAdd comments

Core bbconfig.cache.default LoadersPersisters

Course bbconfig.cache.courseCache LoginActions that courses loaded

Course Map bbconfig.cache.courseMapCache Selecting a course link from the My Institution orCourses tab

Discussion Board bbconfig.cache.dbCache Clicking the collect button for a given forumPerforming different sort, filter, and printoperations on the Collection page

Navigation bbconfig.cache.navAppCachebbconfig.cache.navItemCache

Almost every request that controls how links arerendered

Task bbconfig.cache.taskCache Course evaluation reportBatch course and user operationsOutcomes Assessment batch user casesDeployment managerManage Materialized ListManage surveysAny message action related to discussion board


9.1 S

P6 BETA D

RAFT


Performance Settings

How to Edit the Content Management Performance Settings1. In the Blackboard Learn Administrator Panel, click Technical Settings, and then click

Performance Settings.2. Edit the fields using the information in the following table, which describes each field and its

recommended setting.

Field Name DescriptionRecommendedSetting

File CacheSize

Size of the file cache The system can cache the contents of files in memory toimprove performance.

1-100MB

QueryStatementCacheEnabled

Whether the caching of query statements is enabled The system can cachequery statements to improve performance if the same query is performedmultiple times. If Yes is selected, queries are cached. The default value is Yes.

Yes

MaximumResponsesto Search

Maximum number of resources returned in response to a WebDAV resourcesearch requestThis setting prevents the system from overloading with one request. Thedefault value returns 1000.

100-1000

TransactionalChange SizeLimit

Maximum number of resources returned in response to a WebDAV resourcesearch request This setting prevents the system from overloading with onerequest. The default value returns 1000.

100-1000

3. Click Submit.

Document Store SettingsMake sure to check the Document Store settings for the content management document store andmakeadjustments based on actual usage.

How to Edit the Content Management Document Store Settings1. In the Blackboard Learn Administrator Panel, click Technical Settings, and then click Document

Stores.2. In the contextual menu for aDocument Store, click JDBC Settings. The following table

describes the available fields.


ConnectionExpiration

Number of minutes before a live connection is expired to release the memoryused

5


9.1 S

P6 BETA D

RAFT



MaximumConnections

Maximum number of connections in the connection poolThis setting limits the size of the connection pool to allow maximum performance.Depending on the database configuration and hardware, too many connectionscan lower performance.

The default setting of 50 means that the system can support up to 50 connectionsto that particular storage location at one time from each application server. Often itis necessary to increase this value if images or other content is loaded regularly,such as from the My Institution page. In this case, you would also increase theMinimum Connections.In rare cases, the Maximum Connections could be set as high asbbconfig.httpd.maxclients to ensure that a connection is available for eachpossible incoming client connection.

Note: This should only be done for those storage databases that are being usedvery heavily.

100

MinimumConnections

Minimum number of connections in the connection poolThis setting limits the size of the connection pool to allow maximum performance.Too few connections can lower system performance.

For all storage databases, regardless of usage, this should not be set below 5.This allows for some standing connections to remain even when the system ismostly idle. Building up connections is very work intensive, and because it isserialized (only one new connection can be added at a time), locking issues willoccur if the minimum connections are set too low.

10

DeadConnectionTimeoutPeriod

Number of seconds before a connection to the document store database isconsidered “dead” and is deleted from the connection pool

300

3. Click Submit.

Enabling Tomcat Thread QueuingWhen a request comes into the web server (Apache or IIS), the web server passes it to the application server.A finite number of application server threads are available for these connections, and when they have all beenconsumed, all additional requests will be dropped. This results in errors for the user, such as a page not loading.To add all additional requests to a queue instead of dropping them, enable Tomcat thread queuing. Althoughusers might have to wait slightly longer for their request to be processed, they are less likely to have theirrequest dropped.

Tomcat thread queuing can be enabled temporarily or permanently. If it is enabled temporarily, the changeremains in effect only until a PushConfigUpdates command is run.

How to Temporarily Enable Tomcat Thread Queuing1. Stop the Blackboard Learn application.2. Open the server.xml file in the following directory:

UNIX:

%/usr/local/blackboard_directory/apps/tomcat/conf

Windows:

C:\ blackboard_directory\apps\tomcat\conf


9.1 S

P6 BETA D

RAFT


3. Change the value of the backlog attribute from 0 to 10 to increase the number of requests that willbe placed on the Tomcat queue if no Tomcat threads are available to process a request from theweb server:<Connector port="8009"

backlog="0"enableLookups="false"minThreads="1"maxThreads="40"protocol="org.apache.jk.server.JkCoyoteHandler"soTimeout="20000"

tomcatAuthentication="false"URIEncoding="UTF-8"useBodyEncodingForURI="true"useURIValidationHack="false" />

4. Save and close the file.5. Restart the Blackboard Learn application.

Note: The server.xml file will be overwritten each time the PushConfigUpdates command is run. Tomake changes permanent, follow the steps in the next section.

How to Permanently Enable Tomcat Thread Queuing1. Open the server.xml.bb file in the following directory:

UNIX:

%/usr/local/blackboard_directory/config/tomcat/conf

Windows:

C:\blackboard_directory\config\tomcat\conf

2. If Tomcat clustering is in use, open the server.xml.template file in the following directory:

UNIX:

%/usr/local/blackboard_directory/config/tomcat/cluster/ conf

Windows:

C:\blackboard_directory\config\tomcat\cluster\conf\

3. In both files, change the value of the backlog attribute to at least 10 to increase the number ofrequests that will be placed on the Tomcat queue if no Tomcat threads are available to process arequest from the web server. You change increase this value as needed.<Connector port="@@bbconfig.appserver.portnumber@@"

backlog="10"

enableLookups="false"

minThreads="@@bbconfig.appserver.minthreads@@"

maxThreads="@@bbconfig.appserver.maxthreads@@"

protocol="@@bbconfig.jk_connector.classname@@"

soTimeout="20000"

tomcatAuthentication="false"

URIEncoding="UTF-8"

useBodyEncodingForURI="true"

useURIValidationHack="false" />


9.1 S

P6 BETA D

RAFT


4. Save and close the files.5. Update the configuration by running the PushConfigUpdates command:

l UNIX:%/usr/local/blackboard_directorytools/admin/ PushConfigUpdates.sh

l Windows:C:\blackboard_directory\tools\admin\ PushConfigUpdates.bat

6. If Tomcat clustering is in use, update each cluster node by running the UpdateClustercommand:

l UNIX:%/usr/local/blackboard_directorytools/admin/ UpdateCluster.sh

l Windows:C:\blackboard_directory\tools\admin\ UpdateCluster.cmd

Installing One or More Tomcat ClustersThis section includes all of the procedures needed to install and configure Tomcat Application Clusters. Theseprocedures assume an Administrator has full administrative rights as either administrator or root.

Before Installing a ClusterThe server must be configured to support clustering prior to installing a Tomcat Cluster node. Clustering isdisabled by default andmust be enabled. Installing a cluster requires that the application instance be shutdownand restarted.

How to Configure in Windows1. Navigate to the following directory:

blackboard_directory\config

2. Open the bb-config.properties file.3. Search for the bbconfig.tomcat.cluster.enable variable, andmodify the default value



each node.6. Navigate to the following directory:


7. Launch the Push Config Updates script by running the PushConfigUpdates.bat file.8. Create a new ServerGroup in Blackboard Learn9. Navigate to the following directory:


10. Create a ServerGroup with a specified port number by running the following command:ServerGroupManager.bat -c -n new_group_name -p new_port_number


9.1 S

P6 BETA D

RAFT


How to Configure in UNIX1. Navigate to the following directory:

blackboard_directory/config

2. Open the bb-config.properties file.3. Search for the bbconfig.tomcat.cluster.enable variable, andmodify the default value



each node.6. Navigate to the following directory:

blackboard_directory/tools/admin

7. Launch the Push Config Updates script by issuing this following command:./PushConfigUpdates.sh

8. Create a new ServerGroup in Blackboard Learn9. Navigate to the following directory:


10. Create a ServerGroup with a specified port number by issuing the following command:./ServerGroupManager.sh -c -n new_group_name -p new_port_number

Note: In aWindows or UNIX load-balanced environment, the PushConfigUpdates script mustbe run on each load-balanced server. Each Nodemust have its own ServerGroup.

Installing a Cluster NodeThese procedures assume that the Administrator has full administrative rights as either administrator or root.Upon creating an individual cluster node, the Blackboard services will need to be shutdown and restarted inorder to reset the configuration with the new clustered node.


ClusterID

Must be a unique name with no spaces between any of the letters. Best practice is to identify onenaming convention for all nodes and increment numerically to differentiate servers and nodes.Example: Blackboard1 or Blackboard2.

ServerShutdownPort

Must be a unique port in order to connect to the JVM for the clustered node and shut it down. Bydefault the primary application server installed with Blackboard runs on port 8005, therefore a newvalue must be supplied to avoid port socket contention. Best practice is to increment the current servershutdown port by 1000.

JKConnectorPort

Must be a unique port in order for the web server to communicate to each clustered node. The defaultport is 8009. Best practice is to increment the current jk connector port by 1000.

ClusterListenerPort

Must be a unique port for the cluster to replicate session information across the wire. The default portis 4000. Best practice is to increment the current listen port by 1000.

How to Install in Windows1. Launch the Install Cluster script by running the InstallCluster.bat file. After running the file,

you will be prompted for the following information. Configure the settings according to the previous


9.1 S

P6 BETA D

RAFT


table.l Cluster ID

l Server Shutdown Port

l JK Connector Port

l Cluster Listener Port

2. The cluster is now created.3. Stop your server by running the following command:

ServiceController.bat services.stop

4. Start your server by running the following command:ServiceController.bat services.start

How to Install in UNIX1. Launch the Install Cluster script by issuing ./InstallCluster.sh After running the command,

you will be prompted for the following information. Configure the settings according to the previoustable.

l Cluster ID

l Server Shutdown Port

l JK Connector Port

l Cluster Listener Port

2. The cluster is now created.3. Stop your server by issuing the following command:

./ServiceController.sh services.stop

4. Start your server by issuing the following command:./ServiceController.sh services.start

5. Run the jps command from your JAVA_HOME to see the bootstrap processes. You should see oneTomcat Process, and the number of Cluster Process IDs.

Tip: UNIX customers should increase the Apache MaxClients value as they add nodes.Blackboard recommends multiplying the initial value by the number of total JVMs. For example, ifMaxClients is 500 for a non-clustered configuration, when 2 JVMs are added, this setting shouldincrease to aminimum of 1500.

Files that are AffectedAfter a cluster is installed, there are a number of files and directories that are produced. The following tablehighlights some of these files and directories.


blackboard_directory/apps/tomcat/cluster/

A new directory that is created when the first node (other than root)is installed.

blackboard_directory/apps/tomcat/cluster/node_id

A new directory that is created for every node added.Each directorycontains files affecting that node: …/conf/server.xml and logfiles.

blackboard_directory/apps/tomcat/conf/jk/workers.properties

This file exists before adding a node but changes whenever a nodeis added to include load-balancing information for that node. Tolearn more about the workers.properties file, seehttp://tomcat.apache.org.


9.1 S

P6 BETA D

RAFT

http://tomcat.apache.org/tomcat-3.3-doc/Tomcat-Workers-HowTo.html



server.xml A file that allows you to configure Tomcat nodes through the use ofXML descriptors.

Troubleshooting Installation IssuesThis topic contains three steps to take if the Tomcat Cluster is not functioning as expected.

1. Check that the following value is present and set to true in the bb-config.properties filelocated in the following blackboard_directory/config directory:bbonfig.tomcat.enable=true

If it is set to false, then run PushConfigUpdates.bat to change it. To learnmore, see BeforeInstalling a Cluster.

2. Check that the workers.properties file contains the correct information for all of the nodesinstalled in the cluster. To learnmore about the workers.properties file, see Files that areAffected.

3. Watch the Java processes running on your application server. There should be a Java processrunning for each node installed and one for the root node. CPU processing should be distributedacross the nodes.

Enabling Cache ReplicationBy default, Blackboard Learn will install with cache replication in a cluster disabled. To enable replication,manually configure the setting and restart the application servers.

How to Enable Replication in Windows1. Navigate to the following directory:

blackboard_directory\config\internal/

2. Open the ehcache.xml file.3. Search for the two cacheManagerxxx elements, and remove the comments.4. Additional information is located within the ehcache.xml file, specific to the elements.5. Stop your server by running the following command:

ServiceController.bat services.stop

6. Start your server by running the following command:ServiceController.bat services.start

How to Enable Replication in UNIX1. Navigate to the following directory:

blackboard_directory/config/internal/

2. Open the ehcache.xml file.3. Search for the two cacheManagerxxx elements, and remove the comments.

1. Additional information is located within the ehcache.xml file, specific to the elements.2. Stop your server by issuing the following command:

./ServiceController.sh services.stop


9.1 S

P6 BETA D

RAFT

Performance Optimization > SQL

3. Start your server by issuing the following command:./ServiceController.sh services.start

After restarting, all caches that aremarked as bbconfig.cache.cache_name.needsclusterinvalidation=true in cache-settings.properties will send invalidation notificationsto all nodes in the system when entries are removed/flushed/updated.

Removing a Cluster NodeThese procedures assume an Administrator has full administrative rights as either administrator or root. Uponremoving an individual cluster node, the Blackboard services will need to be shutdown and restarted in order toreset the configuration without the clustered node.

How to Remove in Windows1. Navigate to the following directory:


2. Stop your server by running the following command:ServiceController.bat services.stop

3. Launch the Remove Cluster script by running the following command:RemoveCluster.bat

4. Specify the cluster to be deleted when prompted.5. Start your server by running the following command:

ServiceController.bat services.start

How to Remove in UNIX1. Navigate to the following directory:


2. Stop your server by issuing the following command:./ServiceController.sh services.stop

3. Launch the Remove Cluster script by issuing the following command:./RemoveCluster.sh

4. Specify the cluster to be deleted when prompted.5. Start your server by issuing the following command:

./ServiceController.sh services.start

6. Verify the cluster was successfully removed by running the jps command from your JAVA_HOMEto see the bootstrap processes.

SQL

Pre-Installation Recommendations in a SQL EnvironmentThis section provides best practices for configuring the hardware environment in whichMicrosoft SQL Server2005/2008 will reside.

Before continuing, read the following information:


9.1 S

P6 BETA D

RAFT


l Guidance Provided by Microsoft (2005)l Guidance Provided by Microsoft (2008)l SQLServer I/O Basics (2005)l Analyzing I/O Characteristics (2008)

Pre-Allocating LUNs in SQLWhen setting up the SQL Server 2005/2008 environment, Blackboard recommends creatingmultiple logical unitnumbers (LUNs) for specific purposes to reduce the amount of unnecessary paging.

Blackboard recommends creating a LUN for each of the following:

l TheWindows Operating System

Note: Size this LUN to handle the full installation of the Operating System only.

l The paging file (optional)l The SQL Server 2005/2008 product installationl The TEMPDB space

After Blackboard Learn has been installed, configure additional LUNs for the Blackboard schemas. CreateLUNs for each schema or create a subset of LUNs based on data file growth and usage. Data files andtransaction logs should always reside on separate LUNs.

Blackboard recommends that creating an additional LUN for each of the following:

l The BBLEARN (legacy: BB_BB60) schema data filel The BBLEARN (legacy: BB_BB60) schema transaction logl The remaining Blackboard schema data filesl The remaining Blackboard schema transaction logs

In total, eight LUNs would be pre-allocated:

l LUN 1: Operating Systeml LUN 2: Windows Paging File (Optional)l LUN 3: SQL Server 2005/2008 Product Installationl LUN 4: TEMPDB Filesl LUN 5: BBLEARN (legacy: BB_BB60) Data Filel LUN 6: BBLEARN (legacy: BB_BB60) Transaction Logl LUN 7: Remaining Blackboard SchemaData Filesl LUN 8: Remaining Blackboard Schema Transaction Log

Configuring the Paging FileThe paging file is a hidden file that resides on the boot partition of a server. TheWindows Operating Systemuses the paging file as additional random access memory (RAM). The paging file and physical memoryconstitute the virtual memory.

The default paging file size is equal to three times the total RAM. The primary reason for configuring such alarge paging file is to have a file large enough to handle a SQL Server memory dump during a software failure.

When the paging file resides on the boot partition, Windows must perform disk read and write requests to boththe system folder and the paging file. Placing the paging file on a different partition reduces competitionbetween read and write requests. To enhance performance, Blackboard recommends placing the paging file on


9.1 S

P6 BETA D

RAFT

http://msdn.microsoft.com/en-us/library/ms143719(SQL.90).aspx





http://msdn.microsoft.com/en-us/library/bb500469(v=SQL.100).aspx





http://www.microsoft.com/technet/prodtechnol/sql/2005/iobasics.mspx





http://technet.microsoft.com/en-us/library/ee410782(SQL.100).aspx





a different partition as well as on a different physical hard disk drive so that Windows can handlemultiple I/Orequests quickly.

Configuring SQL Server SettingsFor themost part, SQL Server is a fairly independent, self-tuning system that adjusts to the workloads of theuser community. To further improve performance, modify the following values using the SQL ServerManagement Studio:

l Max Degree of Parallelism: TheMax Degree of Parallelism (MAXDOP) is a configuration indicatinghow the SQL Server optimizer will use the CPUs. This is a server-wide configuration that by defaultuses all of the CPUs to have the available portions of the query executed in parallel. The defaultMAXDOP configuration for SQL Server is 0; however, Blackboard recommends lowering this settingto lower than n – 1, where n is equal to the number of CPUs. In the Blackboard PerformanceEngineering Laboratory, theMAXDOP is often to set to a value of 1. Rarely has there been aperformance difference by setting the value from 1 to any number higher than 1. Query parallelism canbecome aCPU resource saturation problem when the database optimizer incorrectly distributes thequery across multiple CPUs. To determine whether an unlimitedMAXDOP setting is causing highsynthetic CPU utilization, look for the wait event CXPACKET (Wait Event Category of Parallelism).TheMAXDOP does not work in some versions of SQL Server 2008, to avoid this issue, visithttp://support.microsoft.com/kb/970399

l Address Windowing Extensions (AWE): AWE allows 32-bit operating systems to access largeamounts of memory. It is exposed by the operating system and is implemented with slight differencesdepending on the operating system version. To run locked pages inmemory, the SQL Serveroperating system user account must have administrative permissions. After enabling and configuringAWE from the SQL Server Administration console, SQL Server will now be able to take advantage ofmore than 2GB of memory. To learnmore, see http://msdn.microsoft.com/en-us/library/ms187499.aspx.

Note: AWE can be enabled and configured on a 64-bit operating system. To learnmore, seehttp://blogs.msdn.com/slavao/archive/2005/04/29/ 413425.aspx.

l Maximum Worker Threads: MaximumWorker Threads are SQL Server threads that execute user orbatch requests. A worker is bound to a batch until it completes, so themaximum number of workerslimits the number of batches that execute concurrently. Blackboard recommends using the defaultsetting of 0 because it will spawn the appropriate number of Worker Threads based on need. To learnmore, see http://msdn.microsoft.com/en-us/library/ms187024.aspx.

l Fiber Mode: Fiber mode, also known as lightweight pooling, should not be used as it can causecertain features to fail. To learnmore, see http://msdn.microsoft.com/en-us/library/aa175385(SQL.80).aspx and http://msdn.microsoft.com/en-us/library/ms189267.aspx.

Configuring READ_COMMITTED_SNAPSHOT Isolation LevelThe READ_COMMITTED_SNAPSHOT database option determines "what locks SQL Server takes whenaccessing data and, therefore, by extension, they determine the level of concurrency and consistency thatstatements and transactions experience." Quotation taken from Craig Freedman's SQL Server Blog: "ReadCommitted Isolation Level". To learnmore about the option, see http://msdn.microsoft.com/en-us/library/ms173763.aspx.

READ_COMMITTED_SNAPSHOT specifies that data read by any statement in a transaction will be thetransactionally consistent version of the data that existed at the start of the transaction. The transaction canrecognize only those datamodifications that were committed before the start of the transaction. Datamodifications made by other transactions after the start of the current transaction are not visible to statements


9.1 S

P6 BETA D

RAFT

http://support.microsoft.com/kb/970399



http://blogs.msdn.com/slavao/archive/2005/04/29/413425.aspx




http://msdn.microsoft.com/en-us/library/aa175385(SQL.80).aspx

http://msdn.microsoft.com/en-us/library/aa175385(SQL.80).aspx



http://blogs.msdn.com/craigfr/archive/2007/04/25/read-committed-isolation-level.aspx












executing in the current transaction. The effect is that the statements in a transaction get a snapshot of thecommitted data as it existed at the start of the transaction.

Blackboard recommends setting READ_COMMITTED_SNAPSHOT to ON for the BBLEARN (legacy: BB_BB60) schema:

ALTER DATABASE BBLEARN

SET READ_COMMITTED_SNAPSHOT ON

GO

To disable READ_COMMITTED_SNAPSHOT, change the value to OFF:

ALTER DATABASE BBLEARN

SET READ_COMMITTED_SNAPSHOT OFF

GO

Working with the TEMPDB in a SQL EnvironmentThe TEMPDB is one of themost critical areas for optimizing performance of SQL Server. Most complex queryoperations take place in this region of SQL Server. When configured incorrectly, performance can be affecteddramatically.

By default, the space is not meant to shrink (nor do we recommend auto-shrinking the space), but a penaltydoes exist for this space growing. Size this space carefully based on the needs of the application.

The TEMPDB is often sized to 8MB by default. It continues to grow as long as the SQL Server is online.Restarting the SQL Server process will force the TEMPDB to return to its default size. This is why users oftencomplain about the overall responsiveness of the system after maintenance. Part of the problem could be thatthe TEMPDB needs to grow, but another factor could be the flushing of the procedure cache during the restartoperation. The culprit of slow performing queries on a system with a poorly configured TEMPDB is oftenlatency caused by TEMPDB data file growth.

Sizing the TEMPDBBlackboard recommends the following when sizing the TEMPDB:

l To determine the actual TEMPDB size needed, pre-size the TEMPDB to 2GB and let it grow overseveral days of high usage.

l To determine the data file size for each CPU, divide the actual TEMPDB size by the number of CPUsavailable.

l To enable the last file to grow if additional storage is needed, disable auto-growth for each of the datafiles except the last one.

For example, suppose that an 8 CPU server needs roughly 4GB of actual TEMPDB space. Configureeight data files, each pre-sized to 512MB. Disable auto-growth for the first seven files, and enableauto-growth for the final file.

Using the SQL 2005 Server Performance DashboardMicrosoft provides an open source diagnostic tool called SQL Server Performance Dashboard. ThePerformance Dashboard reports enable SQL Server Administrators and other users tomonitor the health of theSQL Server and diagnose issues.

Although it relies upon Reporting Services definition files (.rdl), Reporting Services does not need to beinstalled to use the Performance Dashboard Reports. This custom report set relies on SQL Server’s dynamic


9.1 S

P6 BETA D

RAFT


management views (DMVs) as a data source, which provides the wealth of data that the dynamic managementviews contain but insulates the user from the views and underlying structures.

Accessing and using this storehouse of performance information does not require additional sources, datacapture, or tracing. Other obvious benefits of using these prefabricated views include the constant availabilityof the information that they contain and their inexpensive nature (from the tandem perspective of collection andquerying) as a source of server monitoring.

The Performance Dashboard provides roughly one hour of system history. It is an effective tool for performingimmediate forensics when a problem is reported, but it cannot be used for long-term monitoring.

To download the tool fromMicrosoft, go to http://www.microsoft.com/downloads/details.aspx?FamilyId=1d3a4a0d-7e0c-4730-8204-e419218c1efc&displaylang=en.

To learnmore about getting themost out of the Performance Dashboard, see Related Resources.

The Performance Dashboard is no longer available in SQL 2008. Microsoft has released a new tool called theData Collector, to learnmore about the Data Collector, visit http://msdn.microsoft.com/en-us/library/bb677180(v=SQL.100).aspx. For comprehensive documentation about the SQL Server 2008Management DataWarehouse, visit Microsoft's website at http://msdn.microsoft.com/en-us/library/dd939169(SQL.100).aspx

Tracking Wait Events and QueuesWaits and queues can be used to identify performance improvement areas within SQL Server. Wait eventsindicate where SQL Server is spending time waiting instead of servicing a request. When a request is waiting,the response time experience of a user is affected directly. The longest wait events highlight themost importantor relevant queues (that is, PerformanceMonitor counters and other data). The wait event information can beextracted easily from the Performance Dashboard.

For information about themethodology and each of the wait events, seehttp://www.microsoft.com/technet/prodtechnol/sql/bestpractice/performance_tuning_ waits_queues.mspx.

Monitoring Key AreasIn its Troubleshooting Performance Problems in SQL Server 2005 document, Microsoft recommendsmonitoring the key areas and counters in SQL Server listed in the following table.

Area Name:Counter Name Description

Memory:Pages/sec

Rate at which pages are read from or written to disk during hard page faultsAs the memory pages are transferred to and from the relatively slow disk storage, the system willexperience slow performance. Although it may spike occasionally, this counter should average20 or less. If the counter is too high on a regular basis, add memory to the server.

Memory:AvailableBytes

Amount of physical memory available for allocation At least 5MB of RAM should be available. If the amount available is less than 5MB, consider adding RAM to the server.

NetworkInterface:Bytes Total/sec

Per-second rate at which data is passing though the network interface card (NIC)


9.1 S

P6 BETA D

RAFT

http://www.microsoft.com/downloads/details.aspx?FamilyId=1d3a4a0d-7e0c-4730-8204-e419218c1efc&displaylang=en








http://msdn.microsoft.com/en-us/library/dd939169(SQL.100).aspx

http://msdn.microsoft.com/en-us/library/dd939169(SQL.100).aspx

http://www.microsoft.com/technet/prodtechnol/sql/bestpractice/performance_tuning_waits_queues.mspx




http://www.microsoft.com/technet/prodtechnol/sql/2005/tsprfprb.mspx







Performance Optimization > Oracle

Area Name:Counter Name Description

Physical Disk:%Disk Time

Percentage of time that the disk is busy Although it may spike occasionally, this counter shouldbe less than 55% during any sustained period. If the counter is too high, consider doing one ormore of the following:

l Add drives to the array to increase the spindles and spread the load.

l Add additional channels.

l Change the RAID version to a higher performance version (for example, RAID 5 toRAID 0+1).

Physical Disk:Avg. DiskQueueLength

Number of disk requests that are waiting in the queue According to queuing theory, this countershould be less than 2 over any sustained period or the queue could become backlogged. If thecounter is too high, consider doing one or more of the following:

l Add drives to the array to increase the spindles and spread the load.

l Add additional channels.

l Change the RAID version to a higher performance version (for example, RAID 5 toRAID 0+1).

Processor:%ProcessorTime

Time that the processor is doing actual work This value is calculated by measuring thepercentage of time that the processor is idle and subtracting that from 100 to get the time theprocessor is busy doing work. Although it will spike occasionally, this counter should be lessthan 80% over any sustained period. If this counter is too high, consider adding or upgrading theprocessors on the server.

System:ProcessorQueueLength

Number of threads in the processor queue Even on computers with multiple processors, a singlequeue exists for processor time. If this exceeds 2 per processor (that is, 4 on a 2-processorserver or 8 on a 4-processor server), consider adding or upgrading the processors on theserver.

Oracle

Pre-Installation Recommendations in an Oracle EnvironmentThis section provides best practices for configuring the hardware environment in which Oracle will reside.

Note: Most hardware and storage vendors provide specific guidance for designing a high performanceOnlineTransaction Processing (OLTP) Oracle environment as part of the installation and set-up activities. Beforeinstalling Oracle, contact the vendor to obtain the best practices for configuring the storage sub-system.

Configuring the Storage ConfigurationFrom a product installation and data file perspective, Oracle has the flexibility to be deployed in a variety ofstorage configurations. Oracle Blackboard Learn deployments can use any of the following configurations:

l Network File System (NFS)l ISCSI (IP-SAN)l Fiber-Channel SANl Local disks (SCSI/JBOD)

Themajor hardware and storage vendors have publishedmany performance benchmarks regarding whichstorage platform provides the best overall performance. Blackboard leaves it up to each client to make the bestdecision with regard tomaintainability, growth, and cost.


9.1 S

P6 BETA D

RAFT


Note: NetApp™ is a storage vendor in the NFS space that also has ISCSI and Fiber-Channel SANdeployments. To learnmore about storage configuration options, see their white paper describing performancedifferences across the three storage configurations.

Forecasting Memory UtilizationOracle offers automatic tuning capabilities that simplify the performancemanagement process for databaseadministrators. To address memory management, regularly measure the following four aspects:

l Host Operating Systeml System Global Area (SGA)l High-Watermark of Connectionsl Program Global Area (PGA)

Blackboard recommends allocating roughly 10% to 20% of available memory to the operating system, and thencalculating the connection high-water mark to identify the demands of PGA.

When not using the Oracle multi-threaded server, eachOracle connection can use up to 2MB of RAM.Additionally, factor in the SORT_AREA_SIZE and HASH_AREA_SIZE, which are session-controlled variables.

Sizing the System Global AreaOracle offers the ability to auto-size the System Global Area (SGA) using an automatic tuningmechanism. Bysetting the SGA_TARGET to a particular memory allocation and setting STATISTICS to TYPICAL, Oracle willbe able to decide when tomovememory between the database cache and the shared pool. If a dedicated DBAis not available to study SGA utilization andmake appropriate forecasting changes, this makes sense as aviable setting.

For guidance on whether to use an automatic tuning approach and the best approach to doing so, see ImprovingSQL Statement Tuning with Automatic SQL Tuning.

The following table provides a short summary of the key SGA components. If manually tuning the SGA region,it is imperative that the DBA forecast thememory needs of the system. This requires a set of exercises tocharacterize the workload, as well as account for unexpected utilization increases when demand in notnecessarily transparent. Blackboard recommends accounting for a 20% spike.

SGAComponent

InitializationSetting

Areas OfInfluence Description

SharedPool:LibraryCache

SHARED_POOL_SIZE

Shared SQLareasPrivate SQLareasPL/SQLproceduresandpackagesVariouscontrolstructures

Oracle needs to allocate and deallocate memory as SQL or proceduralcode is executed based on the individual needs of users' sessions andin accordance with the LRU algorithm.

SharedPool:DictionaryCache

SHARED_POOL_SIZE

Row cacheLibrarycache

Highly-accessed memory structures that provide information aboutobject structures to SQL statements being parsed.


9.1 S

P6 BETA D

RAFT

http://media.netapp.com/documents/tr-3423.pdf


http://www.oracle.com/technetwork/testcontent/ast-082393.html









SGAComponent

InitializationSetting

Areas OfInfluence Description

Java Pool JAVA_POOL_SIZE

Data in JVM Memory available for the Java memory manager to use for all thingsJava.

StreamsPool

STREAMS_POOL_SIZE

Streamactivity

Memory available for stream processing.

Redo LogBuffer

LOG_BUFFER

Redo Entries Holds changes made to data and allows for the reconstruction of data inthe case of failure.

DatabaseBufferedCache

DB_2K_CACHE_SIZEDB_4K_CACHE_SIZEDB_8K_CACHE_SIZEDB_16K_CACHE_SIZEDB_32K_CACHE_SIZEDB_KEEP_CACHE_SIZEDB_RECYCLE_CACHE_SIZE

Write listLRU list

Holds copies of data requested by SQL and reduces requests to disk byhaving data in memory. Many different buffer caches can help segregateon usage patterns.

Large Pool LARGE_POOL_SIZE

SharedserverI/O serverprocessesBackup andrestore

For large memory allocations.

Sizing the Program Global AreaThe Program Global Area (PGA) is a privatememory region containing data and control information for a serverprocess. Access to it is exclusive to that server process and is read and written only by the Oracle code actingon behalf of it.

Oracle provides automatic PGA memory management to simplify and improve the way in which PGA memoryis allocated. By default, PGA memory management is enabled. In this mode, Oracle dynamically adjusts theportion of the PGA memory dedicated to work areas based on 20% of the SGA memory size. Theminimumvalue is 10MB. Sizing this area depends heavily on factors such as the amount of RAM available on thesystem, the number of processes/connections accessing the system (high-water mark), and the degree of sortand hash area space for query operations.

To learnmore about determining how much PGA is needed, see http://www.scribd.com/doc/6469805/How-to-Determine-if-PGA-Size-is-Set-Properly.


9.1 S

P6 BETA D

RAFT

http://www.scribd.com/doc/6469805/How-to-Determine-if-PGA-Size-is-Set-Properly










Configuring Temporary Tablespaces

Configuring the TEMP TablespaceOracle provides temporary tablespaces that are optimized for the storage of transient data (data available onlyfor the duration of the session). Sort operations are the primary user of temporary tablespaces. For example, iftwo large tables are joined as part of a query, andOracle cannot do the sort in memory, space will be allocatedin a temporary tablespace for performing the sort operation.

The following SQL operations, all of which can be found in Blackboard Learn, might require disk sorting:

l CREATE INDEXl ANALYZEl SELECT DISTINCTl ORDER BYl GROUP BYl UNIONl SORT-MERGE

SORT_AREA_SIZE Initialization ParameterSorting is managed by the SORT_AREA_SIZE initialization parameter, which is managed on a per sessionbasis. For example, if the SORT_AREA_SIZE is set to 16KB and there are 1000 sessions, themaximum sizewould be 16MB. The sort space identified by this parameter is maintained in PGA memory.

Sort operations are attempted first in the PGA sort area, just as well as hash join operations are attempted firstin the PGA hash area. There are different tuning philosophies with regard to pre-allocating space to this regionor making use of automatic PGA memory management mode. Although larger sort and hash areas candramatically improve the performance of a particular operation, they come at the cost of greater memoryutilization. When the size of the work area is smaller than desired, the response time of the request increases.Ideally this work area space is configured for nearly 100% of all single pass online transaction processing(OLTP) operations.

SORT SEGMENT REQUEST Wait EventSorting can bemeasured using the SORT SEGMENT REQUEST wait event. The wait event suggests that auser process tried to acquire a sort segment and had to wait until that segment was obtained. As noted above,the query will attempt to perform the sort operation in memory first. If thememory allocated for the user’s sortspace is insufficient, the process must acquire space in the TEMP tablespace before performing its sort ondisk. This space is called a sort segment.

Although the latency for performing a SORT SEGMENT REQUEST is small (often in themilliseconds), everyopportunity for latency to be applied to the service time of a request adds up. Therefore, it is important tomeasure the effects of sorting on a regular basis.

To learnmore, see http://www.dbazine.com/blogs/blog-cf/chrisfoot/blogentry.2006-04-14.0082403220.

Configuring the REDO TablespaceThe REDO tablespace is used as a temporary storage location prior to Oracle performing changes at the datafile layer.

Enable the REDO advisor using the FAST_START_MTTR initialization parameter.


9.1 S

P6 BETA D

RAFT

http://www.dbazine.com/blogs/blog-cf/chrisfoot/blogentry.2006-04-14.0082403220





Checkingmessages in the alert log is an easy way to determine how fast Oracle is filling and switching logs.The specific message to watching for is "Checkpoint not complete."

To improve performance, increase the REDO tablespace size so that log switching can occur at Oracle’srecommended interval of 15 to 30minutes. To do so, identify the current size of the REDO logmembers fromV$LOG, record the number of log switches per hour, and then increase the size of the log to allow Oracle toswitch at the recommended rate of one switch per 15 to 30minutes.

Configuring the UNDO TablespaceThe UNDO tablespace is used for read consistency, data recovery, and rollback. A database running inautomatic UNDOmanagement mode transparently creates andmanages UNDO segments. Oraclerecommends using automatic undomanagement because it simplifies operational management and removesthe need for manual sizing of UNDO using one or more rollback segment.

Use the UNDO advisor to properly size the UNDO space. Be aware of the state and size of the UNDOtablespace is important when trying to eliminate the ORA-1555: snapshot too oldmessages thatidentify a poorly sized UNDO space from theOracle alert log.

To learnmore, see http://www.oracle.com/technology/oramag/oracle/05-jul/o45tuning.html.

Setting Oracle Initialization ParametersOracle initialization parameters influence the performance characteristics of a running instance of Oracle. Ingeneral, a very simple initialization file with few settings is appropriate in most situations, and the initializationfile should not be themain focus for performance tuning. Performance improvement projects should involve theanalysis of under-performing SQL and the causes of latency, which could be related to physical databasedesign, stale database statistics, system resource saturation, or poorly configured instance configuration.

Understanding the Importance of Optimizer StatisticsOptimizer statistics provide detail about a database and its objects and can be used to select the bestexecution plan for each SQL statement. Physical and logical system statistics also can bemaintained. Thecombination of these statistics, whether managed automatically or manually, can directly affects theperformance or service time of a query.

The following table lists the initialization parameters that directly affect the way statistics are used andsubsequently how they shape the decision of the Optimizer.

Note: These settings are recommendations and should be tested out over time. Oracle has put together a veryinformative guide about achieving the best performance from theOptimizer. To learnmore, seeOraclePerformanceOptimization.

ParameterName Description

RecommendedSetting

OPTIMIZER_MODE

Mechanism for result set retrievalA subset of values are available: ALL_ROWS, FIRST_ROWS_1, FIRST_ROWS_10, FIRST_ROWS_100, and FIRST_ROWS_1000

ALL_ROWS

OPTIMIZER_DYNAMIC_SAMPLING

Controls the level of dynamic sampling performed by the OptimizerThis parameter can introduce overhead because the setting forces the CBO to perform read-ahead scans of tables to capture more accurate estimates.Set this parameter to 0 (no sampling) to 10. By default, this parameter is set to 2, meaningthat the Optimizer will dynamically sample all unanalyzed tables. The number of blockssampled is two times the default number of dynamic sampling blocks.

1 or 2


9.1 S

P6 BETA D

RAFT

http://www.oracle.com/technology/oramag/oracle/05-jul/o45tuning.html


http://download.oracle.com/docs/cd/E11882_01/server.112/e16638.pdf



Performance Optimization > Document Store Settings

ParameterName Description

RecommendedSetting

OPTIMIZER_FEATURES_ENABLE

Umbrella parameter for enabling a series of Optimizer features based on an Oracle releasenumber

Do not change

OPTIMIZER_INDEX_CACHING

Adjusts the behavior of cost-based optimization to favor nested loops joins and IN-listiteratorsSetting this parameter to a higher value makes nested loops joins and IN-list iterators lookless expensive to the Optimizer. As a result, it will be more likely to pick nested loop joinsover hash or sort-merge joins and to pick indexes using IN-list iterators over other indexes orfull table scans. By default, this parameter is set to 0.

80-100

OPTIMIZER_INDEX_COST_ADJ

Tunes the Optimizer behavior for access path selection to be more or less index friendly—that is, makes the Optimizer more or less prone to selecting an index access path over a fulltable scan

10-30

Using the Oracle Wait InterfaceTheOracleWait Interface provides insight and quantification to the causes of latency experienced whenexecuting SQL.

The 10046 trace event is the primary mechanism for studying wait events at a statement level. The BlackboardPerformance Engineering team uses 10046 tracing to investigate the causes of latency combined with 10053tracing to understand the characteristics of the Oracle Cost-BasedOptimizer.

To learnmore, see the article Exploring the Oracle DatabaseWait Interface.

The following two books are excellent resources for learning about wait events and 10046 tracing:

l OracleWait Interface: A Practical Guide to Performance Diagnostics & Tuning

l Optimizing Oracle Performance

Document Store SettingsMake sure to check the Document Store settings for the content management document store andmakeadjustments based on actual usage.

How to Edit the Content Management Document Store Settings1. In the Blackboard Learn Administrator Panel, click Technical Settings, and then click Document

Stores.2. In the contextual menu for aDocument Store, click JDBC Settings. The following table

describes the available fields.


ConnectionExpiration

Number of minutes before a live connection is expired to release the memoryused

5


9.1 S

P6 BETA D

RAFT

http://www.oracle.com/technology/pub/articles/schumacher_10gwait.html






http://www.amazon.com/Oracle-Wait-Interface-Performance-Diagnostics/dp/007222729X











http://www.amazon.com/Optimizing-Oracle-Performance-Cary-Millsap/dp/059600527X



Performance Optimization > bb-config.properties File


MaximumConnections

Maximum number of connections in the connection poolThis setting limits the size of the connection pool to allow maximum performance.Depending on the database configuration and hardware, too many connectionscan lower performance.

The default setting of 50 means that the system can support up to 50 connectionsto that particular storage location at one time from each application server. Often itis necessary to increase this value if images or other content is loaded regularly,such as from the My Institution page. In this case, you would also increase theMinimum Connections.In rare cases, the Maximum Connections could be set as high asbbconfig.httpd.maxclients to ensure that a connection is available for eachpossible incoming client connection.

Note: This should only be done for those storage databases that are being usedvery heavily.

100

MinimumConnections

Minimum number of connections in the connection poolThis setting limits the size of the connection pool to allow maximum performance.Too few connections can lower system performance.

For all storage databases, regardless of usage, this should not be set below 5.This allows for some standing connections to remain even when the system ismostly idle. Building up connections is very work intensive, and because it isserialized (only one new connection can be added at a time), locking issues willoccur if the minimum connections are set too low.

10

DeadConnectionTimeoutPeriod

Number of seconds before a connection to the document store database isconsidered “dead” and is deleted from the connection pool

300

3. Click Submit.

bb-config.properties File

How to Edit the bb-config.properties File1. Open the bb-config.properties file in the following directory:

UNIX:

%/usr/local/blackboard_directory/config

Windows:

C:\blackboard_directory\config

2. Edit the parameters using the information provided in the appropriate section in this document or inthe following table.

3. Save and close the file.4. Update the configuration by running the PushConfigUpdates command. To learnmore, see

PushConfigUpdates.

UNIX:

%/usr/local/blackboard_directory/tools/admin/PushConfigUpdates.sh


9.1 S

P6 BETA D

RAFT


Windows:

C:\blackboard_directory\tools\admin\PushConfigUpdates.bat


9.1 S

P6 BETA D

RAFT


Optimization Parameters in bb-config.properties


Apache HTTP Server

bbconfig.unix.httpd.minspareservers Dynamic mechanism for keeping a minimum numberspare of servers available to handle simultaneousrequests from a browser

5

bbconfig.unix.httpd.maxspareservers Dynamic mechanism for keeping a maximum numberof spare servers available to handle simultaneousrequests from a browser

50

bbconfig.unix.httpd.startservers Number of servers to start initially 10

bbconfig.unix.httpd.maxclients Maximum number of servers allowed to be running

This limits the number of clients that can connect atthe same time. Blackboard Learn is compiled tosupport as many as 5,000 clients.

To avoid keepalive issues, this parameter can be setto a value higher thanbbconfig.appserver.maxthreads. To learn more,see Configuring Database Connections.

Note: For Tomcat cluster configurations, ApacheHTTP Server acts as the main load balancingcomponent. As more instances of Tomcat aredeployed, increase this value for each instance in thecluster.

400-1024

bbconfig.unix.httpd.maxrequestsperchild Number of requests each child process is allowed toprocess before the child dies

Note: Setting this parameter to a higher valuereduces delays that are caused by spawning newApache HTTPD child processes. Prolonged use isnot an issue for Blackboard Learn.

1024-2048

bbconfig.unix.httpd.keepalivetimeout Number of seconds to wait for the next request fromthe same client on the same connection

15

bbconfig.unix.httpd.keepalive Whether to allow persistent connections (more thanone request per connection)

On

bbconfig.unix.httpd.MaxKeepAliveRequests Maximum number of requests to allow during apersistent connection

100

bbconfig.webserver.compression Enables HTTP compression via GZip Yes

Microsoft IIS

bbconfig.webserver.keepalive Whether to allow persistent connections (more thanone request per connection)Always make sure to review the setting with yourhardware load balancer vendor.

1

bbconfig.webserver.keepalivetimeout Number of seconds to wait for the next request fromthe same client on the same connection

15

bbconfig.webserver.compression Enables HTTP compression via GZip Yes

Apache Tomcat Database Connections

bbconfig.appserver.minthreads Minimum number of threads created for Tomcat 100


9.1 S

P6 BETA D

RAFT



bbconfig.appserver.maxthreads Maximum number of threads allocated to Tomcat for32-bit 1.4 GB RAM in the heapspaceThis setting limits the number of requests that can besimultaneously processed by Tomcat. This numbershould match thebbconfig.unix.httpd.maxclients setting forApache on UNIX platforms.Deviating from the suggested maximum setting canhave serious repercussions when searching for usersand courses with minimal filtering.To learn more, see Sizing the Maximum ThreadCount.

2-200

bbconfig.appserver.maxthreads Maximum number of threads allocated to Tomcat for64-bit 4 GB RAM in the heapspace.This setting limits the number of requests that can besimultaneously processed by Tomcat.Deviating from the suggested maximum setting canhave serious repercussions when searching for usersand courses with minimal filtering.This number should match thebbconfig.unix.httpd.maxclients setting forApache on UNIX platforms.To learn more, see Sizing the Maximum ThreadCount.

400-800

bbconfig.min.heap size.tomcat Minimum heap size allocated to the Tomcat JVM 1/2 of or equalto max.heapsize.tomcat

bbconfig.max.heap size.tomcat Maximum heap size allocated to the Tomcat JVM for32-bit configurations

1024-1400m

bbconfig.max.perm size.tomcat Maximum perm space allocated to the Tomcat JVM 256m

bbconfig.max.stack size.tomcat Stack size for each thread in the Tomcat JVM 170-300k

bbconfig.jvm.options.extra.tomcat Additional settings used to configure the JVMTo learn more, see Using Non-Standard (-XX) JVMArguments.

User defined


9.1 S

P6 BETA D

RAFT

Performance Optimization > Related Resources


bbconfig.database.instance.maxpoolsize Maximum number of connections waiting to servedatabase requests

The BBLEARN (legacy: BB_BB60) connection pool isthe primary database connection pool interface forthe Blackboard schema in Tomcat. Blackboardrecommends that this value be sized conservativelybased on need and usage. Start with a maximumvalue of 100, and then increase the maximum size asthe Tomcat application threads increase.

Optimally, this value should be equal to, but notgreater than, thebbconfig.appserver.maxthreads parametersetting.

Note: JDBC connection consumption is a symptomof a performance issue or degradation. Increasing theJDBC connection count will not always solve aperformance issue. Performance issues should bediagnosed with care and accuracy and identifybottlenecks at their source.

300-1024

bbconfig.database.instance.minpoolsize Number of connections waiting to serve databaserequests

10

bbconfig.database.instance.mssql.initpoolsize Initial number of connections waiting to servedatabase requests for SQL Server

10

bbconfig.database.instance.timeout Time window in which database transactions must beprocessed before a timeout occurs

300

Recommended JVM Tuning SetEach release of Blackboard Learn has its own recommended tuning set. To learnmore, see the Release Notesfor the release that you are installing.

Related Resources

Apache HTTP Server for UNIXl General Information about Apache Serverl General Documentation About Apache Server 1.3l Performance Notes for Apache Server 1.3l Apache Server Statusl Apache Benchl Quest Foglight

Microsoft IIS for Windowsl General Documentation about IISl IIS 6.0 Documentation


9.1 S

P6 BETA D

RAFT



http://www.apache.org/





http://httpd.apache.org/docs/1.3






http://httpd.apache.org/docs/1.3/misc/perf-tuning.html






http://httpd.apache.org/docs/1.3/mod/mod_status.html



http://httpd.apache.org/docs/1.3/programs/ab.html

http://httpd.apache.org/docs/1.3/programs/ab.html

http://www.quest.com/foglight

http://www.quest.com/foglight

http://www.iis.net/

http://www.iis.net/

http://www.iis.net/

http://www.iis.net/

http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/848968f3-baa0-46f9-b1e6-ef81dd09b015.mspx




l IIS 7.0 Documentationl Optimizing Performancel ControllingMemory Usagel Monitoring Threads in IISl Monitoring with Performance Counters

Apache Tomcat Application Containerl Java Performance Documentationl Java Performance Tuningl J2SE 5.0 Troubleshooting and Diagtnostic Guidel Analyzing Stack Tracesl Profiling Java Using JProbel A Brief History of Garbage Collectionl Garbage Collection Ergonomics Overviewl JavaGarbage Collection Tuningl Tuning Garbage Collection in the JVMl Shortcuts to Tuning Garbage Collectionl Diagnosing aGarbage Collection Probleml Java HotSpot Garbage Collectionl Java Hotspot VMOptions

Microsoft SQL Serverl Microsoft SQL Server 2005l Guidance provided by Microsoftl SQLServer I/O Basicsl Administering the Database Enginel Microsoft Pre-deployment I/O Practicesl How to Configurere SQL Server to UseMore than 2GBl How to Determine Proper SQL Server Configuration Settingsl SlavaOks’s WebLog: “Be Aware: Using AWE, locked pages inmemory, on 64 bit”l The Perils of Fiber Model Craig Freedman's SQL Server Blog: “Read Committed Isolation Level”l SET TRANSACTION ISOLATION LEVEL (Transact-SQL)l Configuring SQL Server 2005 TempDB for Performancel Optimizing TEMPDB Performancel Flushing of the Procedure Cachel Concurrency Enhancements for the TEMPDB Databasel Working with TEMPDB in SQL Server 2005l Managing Extent Allocations and Free Spacel Tony Rogerson's Blog: "Put TEMPDB on a RAMDrive"


9.1 S

P6 BETA D

RAFT




http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/e621190d-1015-40c2-a5ec-0dcb32c98286.mspx

http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/e621190d-1015-40c2-a5ec-0dcb32c98286.mspx

http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/ad56540c-2323-4316-b981-7ebb70352baa.mspx







http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/b6fd16ee-1192-4b8b-9d02-af307879fdb7.mspx?mfr=true




http://java.sun.com/docs/performance



http://www.javaperformancetuning.com/



http://java.sun.com/j2se/1.5/pdf/jdk50_ts_guide.pdf






http://java.sun.com/developer/onlineTraining/Programming/JDCBook/stack.html



http://www.quest.com/jprobe




http://www.ibm.com/developerworks/java/library/j-jtp10283






http://java.sun.com/j2se/1.5.0/docs/guide/vm/gc-ergonomics.html




http://www.folgmann.com/en/j2ee/gc.html




http://java.sun.com/docs/hotspot/gc5.0/gc_tuning_5.html






http://www.petefreitag.com/articles/gctuning





http://java.sun.com/docs/hotspot/gc1.4.2/example.html





http://java.sun.com/javase/technologies/hotspot/gc/index.jsp








http://www.microsoft.com/sqlserver/2005/en/us/default.aspx
















http://www.microsoft.com/technet/prodtechnol/sql/bestpractice/pdpliobp.mspx






































http://msdn.microsoft.com/en-us/library/aa175385.aspx




















http://searchsqlserver.techtarget.com/tip/0,289483,sid87_gci1180698,00.html







http://technet.microsoft.com/en-us/library/ms175527(SQL.90).aspx



http://www.sql-server-performance.com/articles/per/data_cache_p1.aspx











http://www.microsoft.com/technet/prodtechnol/sql/2005/workingwithtempdb.mspx













http://sqlblogcasts.com/blogs/tonyrogerson/archive/2006/08/24/958.aspx










l Download SQL Server 2005 Performance Dashboard Reportsl Black Belt Administration: Performance Dashboard for Microsoft SQL Server, Part Il Black Belt Administration: Performance Dashboard for Microsoft SQL Server, Part IIl Making theMost Out of the SQL Server 2005 Performance Dashboardl SQLServer 2005Waits andQueuesl Troubleshooting SQL Server Performance

Oracle Databasel Oracle Database 11g R2 Performance Tuning Guidel Oracle Database 10g R2 Performance Tuning Guidel Network Appliance Performance Report: Oracle10g RAC on Linuxl Oracle DatabaseManageabilityl Sizing the Program Global Areal SORT SEGMENT REQUESTWait Eventl Tuning UNDOTablespacel Upgarding from Oracle Database 9i to 10g: What to expect from theOptimizerl Exploring the Oracle DatabaseWait Interfacel OracleWait Interface: A Practical Guide to Performance Diagnostics & Tuningl Optimizing Oracle Performance


9.1 S

P6 BETA D

RAFT








http://www.databasejournal.com/features/mssql/article.php/10894_3665281_2











http://www.databasejournal.com/features/mssql/article.php/10894_3671736











http://www.sql-server-performance.com/articles/per/bm_performance_dashboard_2005_p1.aspx











http://technet.microsoft.com/en-us/library/cc966413.aspx










http://download.oracle.com/docs/cd/E14072_01/server.112/e10821/toc.htm







http://download.oracle.com/docs/cd/B19306_01/server.102/b14211/toc.htm















http://www.oracle.com/technology/products/manageability/database/index10g.html
















http://www.oracle.com/technology/products/bi/db/10g/pdf/twp_bidw_optimizer_10gr2_0208.pdf

































Resources > Elements

Resources

Elements

Category Data Feed ElementsCategory data includes information about the groups that create a catalog structure to Course or Organizationlistings. Within Blackboard Learn, Courses andOrganizations are listed under a category within the coursecatalog or the Organization catalog. The date elements below allow an institution tomap category informationfrom an external course to Blackboard Learn. The link data elements, presented in the next table, then assignCourses or Organizations to a category.

The following table details the category data elements.

Element Description and Data Type

EXTERNAL_CATEGORY_KEY

Must be unique. This field corresponds to the Category Mnemonic field in the UI. Not null. String.Max length 64. Multi-byte characters accepted.

ROW_STATUS Sets the value of the record to one of the following: Enabled: Normal access to the record.Disabled: Record is visible in some areas of the UI, but may not be changed or accessed. Deleted:Record is scheduled to be removed. Passed as a string. “enabled”, “disabled”, “deleted”

AVAILABLE_IND

Establishes category availability within Blackboard Learn. Char(1). Y/N

TITLE The name of the category as it will appear to users within the UI. String. Max length 255. Multi-bytecharacters accepted.

FRONTPAGE_IND

Determines whether or not the category is displayed on the front page of the catalog. Char(1). Y/N

NEW_DATA_SOURCE_KEY

Key used to establish grouping of category elements. String based key. Multi-byte charactersaccepted.

PARENT_CATEGORY_KEY

Identifies the parent category in the category tree. String based key. Multi-byte charactersaccepted.

NEW_EXTERNAL_CATEGORY_KEY

Designates replacement for the current key. String. Max length 64. Multi-byte characters accepted.

AVAILABLE_IND

Available indicator.

CATEGORY Defines the category.

DESCRIPTION Provides a description of the category.

INTERNAL_ID The category's internal identification.

INTERNAL_PARENT_ID

The category's internal parent category identification.

PARENT_BATCH_UID

The category's parent category batch user identification.

REPLACEMENT_BATCH_UID

RESTRICT_IND

NODE_TYPE The type of node.


9.1 S

P6 BETA D

RAFT


Category Membership Data Feed ElementsCategory Membership data creates an association between a Course or Organization and a category.

The following table details the link data elements.


EXTERNAL_CATEGORY_KEY String. Max length 64. Multi-byte characters accepted.Not null

EXTERNAL_COURSE_KEY /EXTERNAL_ORGANIZATION_KEY

Internal numeric Id. Multi-byte characters accepted.Not null

ROW_STATUS Sets the value of the record to one of the following:Enabled: Normal access to the record.Disabled: Record is visible in some areas of the UI, but may not be changed oraccessed.Deleted: Record is scheduled to be removed.Passed as a string. ("enabled", "disabled", "deleted")

AVAILABLE_IND Establishes the Category Membership availability within Blackboard Learn.Char(1). Y/N

NEW_DATA_SOURCE_KEY Designates replacement for the current datasource key.String. Max length 64. Multi-byte characters accepted.

CATEGORY_MEMBERSHIP Defines the category membership.

INTERNAL_ID The internal identification.

INTERNAL_CATEGORY_ID The internal identification for the category.

INTERNAL_GROUP_ID The internal group identification.

MEMBER_ELEMENT

NODE_TYPE The type of node.

Course and Organization Data Feed ElementsCourse information files andOrganization information files are almost identical and, for this reason, are groupedtogether and described in the Course andOrganization Data Feed Elements table. The data elements are, inmost cases, exactly the same for Courses andOrganizations.

The following fields are required to successfully process a Course record:l COURSE_ID

l EXTERNAL_COURSE_KEY

l COURSE_NAME

IMPORTANT! Do not mix Course andOrganization data together in the same feed file.

The following table details the Course data feed elements. Where applicable, the Organization-specific dataelement is included under the Course data element.


9.1 S

P6 BETA D

RAFT



COURSE_IDORGANIZATION_ID

Short name used by the institution to uniquely identify the Course (for example, math101 _F99)The following characters may not be used in Course ID: " () & / ' + "Not null String. Max length 50. Must be unique and cannot be changed.

EXTERNAL_COURSE_KEYEXTERNAL_ORGANIZATION_KEY

Short name used by the Institution to uniquely identify the Course section. This is not displayedto users.Can contain only letters, digits, dashes and periods. No spaces or other punctuation allowed.Must be unique for each Course, and is often the same as the COURSE_ID.Not null, External key. String. Max length 64. Must be unique. Multi-byte characters accepted.

NEW_EXTERNAL_COURSE_KEYNEW_EXTERNAL_ORGANIZATION_KEY

This field is used only on the rare occasions when a Course’s EXTERNAL_COURSE_KEYchanges.String. Max length 64. Must be unique. Multi-byte characters accepted.

COURSE_NAMEORGANIZATION_NAME

Complete title of the Course. The Course Name is used when sorting.String. Max length 255. Multi-byte characters accepted.Not null

ALLOW_GUESTS Allows guest access to the Course.String. y/n

DESCRIPTION Complete description of the Course.String. Max length 4000. Multi-byte characters accepted.

END_DATE Date on which access to the Course ends.Date (yyyy-mm-dd).

START_DATE Date on which access to the Course section begins.Date (yyyy-mm-dd).

NEW_DATA_SOURCE_KEY

Key used to establish a grouping of Course or organization elements.String. Multi-byte characters accepted.

ROW_STATUS Sets the value of the record to one of the following:Enabled: Normal access to the record.Disabled: Record is visible in some areas of the UI, but may not be changed or accessed.Deleted: Record is scheduled to be removed.Passed as a string. ("enabled", "disabled", "deleted")

AVAILABLE_IND Establishes Course or organization availability to Blackboard Learn.Char(1). Y/N

CATALOG Establishes whether the Course or organization appears in catalog.Char(1). Y/N

DESCRIPTION_PAGE

Determines whether or not to display description information in the Course or organizationcatalog.Char(1). Y/N

LOCKOUT_IND Indicates if access to the Course or organization has been restricted. If set to "Y" access to theCourse or organization will be restricted based on the END_DATE and START_DATE.Char(1). Y/N

PACE Indicates if the Course is Instructor-led or self-paced according to the Student.Char(1). Mapping accepted {"Self", "Instructor"}

ABSOLUTE_LIMIT Quota: absolute limit on content uploads in bytes.Numeric.

SOFT_LIMIT Quota: soft limit on content uploads in bytes.Numeric.


9.1 S

P6 BETA D

RAFT



UPLOAD_LIMIT Quota: limit on size of a single upload in bytes.Numeric.

ENROLL_START Date that enrollment may begin.Date (yyyy-mm-dd).

ENROLL_END Date that enrollment is no longer available to Students.Date (yyyy-mm-dd).

ENROLL_OPTION Determines the enrollment method. One of the following strings:Instructor

selfemail

DAYS_OF_USE Number of days that Students may access the Course after enrollment. Useful for self-pacedlearning.Numeric.

DURATION Schedules enrollment window. Options are:Continuous: The Course is always accessible.Range: The Course is accessible in the days between one ENROLL_START and ENROLL_END.Either the beginning date or the end date can be left open-ended to make a Course accessiblefrom a certain date or until a certain date.Fixed: The Course is accessible for a set number of days (DAYS_OF_USE).Char(1). Mapping accepted {"Continuous", "Range", "Fixed"}

INSTITUTION The name of the institution.String. Max length 255. Multi-byte characters accepted.

CLASSIFICATION_BATCH_UID

Sting-based key that establishes an association with a subject area and discipline within theBlackboard Resource Center. This is a deprecated feature in Blackboard Learn (Release 7),but the value is still provided for backward compatibility.

TEMPLATE_COURSE_KEYTEMPLATE_ORGANIZATION_KEY

External key of content source for copy operations.String. Max length 64. Multi-byte characters accepted.

ADMIN_COURSE

ALLOW_ENROLL Allows enrollment to the Course.String. y/n

ALLOW_OBSERVERS Allows observer access to the Course.String. y/n

ASSOCIATIONS

CATALOG

CONTENT_PACKAGE

DESCRIPTION_ELEMENT

Description of the course.

ENROLL_ACCESS_CODE

Access code for enrollment to the course.

ENROLLMENT_TYPE Type of enrollment.

FEE Fee associated to the course.

GROUP_TYPE

INTERNAL_ID The internal identification for the course.


9.1 S

P6 BETA D

RAFT



INTERNAL_CLASSIFICATION_ID

The internal classification identification for the course.

INTERNAL_BUTTONSTYLES_ID

LMS_INTEGRATION

LOCALE The locale for the course.

LOCALE_ENORCED_INDICATOR

LOCKOUT_INDICATOR

PROXY_INDICATOR

NAV_STYLE Navigation style for the course.

RESTRICT Restrictions to the course.

SERVICE_LEVEL

SUB_DOC_UID

TEMPLATE_BATCH_UID

The course's template identification.

TIMEFRAME

TITLE The title of the course.

X_LMS_COPY_IMS_SOURCE

X_LMS_COPY_IMS_ID

X_LMS_IS_PROXY

Enrollment and Staff Students Data Feed ElementsMembership data includes two subclasses: Enrollment and Staff Students. Enrollment requires a ROLE ofStudent, while Staff Students require any role including Student. Each subclass, enrollment and staff Students,may be input in separate feed files. Alternatively, all datamay be included in a Staff Student feed file. Localpolicies and data source key management will determine whether Student enrollments should be included instaff Students, or processed as enrollments. Note that including a user with a role other than Student or Guestin an enrollment (ENR_SNPSHT) will cause that record to fail.

Enrollment information files can also contain Organizationmembership information. The primary key forenrollments is a composite of the user ID and the Course or Organization ID. Enrollment files may only addusers to a Course or Organization as a Student or member respectively. Staff Students must be input in aseparate file that can contain staff Students for Courses andOrganizations as well as Student enrollments.

The following table details the Enrollment and Staff Students data feed elements.


EXTERNAL_COURSE_KEYEXTERNAL_ORGANIZATION_KEY

Used to look up appropriate keys. This is the same key used to identify the Course orOrganization.This is the same key as the Course.Not Null, external key. Multi-byte characters accepted.


9.1 S

P6 BETA D

RAFT



EXTERNAL_PERSON_KEY

Used to look up appropriate keys. This is the same key used to identify the user.Not Null, external key. Multi-byte characters accepted.

ROLE The user’s role in the Course. String. The valid values for the Course Role are: Instructor,teaching_assistant, course_builder, Grader, Student, guest, none.Not Null.

ROW_STATUS Sets the value of the record to one of the following:Enabled: Normal access to the record.Disabled: Record is visible in some areas of the UI, but may not be changed oraccessed.Deleted: Record is scheduled to be removed.Passed as a string. ("enabled", "disabled", "deleted).

AVAILABLE_IND Establishes enrollment availability in Blackboard Learn.Char(1). Y/N

LAST_ACCESS_DATE

The last time the user accessed materials for an associated Course.Date.

LINK_NAME_1 Link name for a user’s home page within a Course. Each user may have a maximum of threehome pages within a Course.String. Max length 100. Multi-byte characters accepted.

LINK_URL_1 Link URL for a user’s home page within a Course. Each user may have a maximum of threehome pages within a Course.String. Max length 100

LINK_DESC_1 Link description for a user’s home page within a Course. Each user may have a maximum ofthree home pages within a Course.String. Max length 255. Multi-byte characters accepted.







INTRODUCTION Introduction information for User Home Page within the Course.String. Max length 4000. Multi-byte characters accepted.

PINFO Personal Information for User Home Page.String. Unlimited. Multi-byte characters accepted.

NEW_DATA_SOURCE_KEY

Used to assign a new datasource key on the rare occasions that the datasource key mustchange.Multi-byte characters accepted.


9.1 S

P6 BETA D

RAFT



CARTRIDGE_ACCESS

Defines access to common course cartridge.

ENROLLMENT_DATE The enrollment date.

INCLUDED_IN_ROSTER

Define inclusion in the roster.

INTERNAL_ID The internal identification.

INTERNAL_GROUP_ID

The internal group identification.

INTERNAL_PERSON_ID

MEMBERSHIP_ELEMENT

MEMBERSHIP

NOTES

PRIVATE_INFORMATION

RECEIVE_EMAIL Designate the ability to receive email.

ROLE_TYPE The role type.

ID_TYPE The identification type.

WEBCT_INHERITED_MEMBERSHIP

Define inherited WebCT membership setting.

Observer Association Feed ElementsTo associate Observers with the Students they will observe. The following table outlines the fields included in arecord in a Snapshot Observer Association feed.

Element Description

EXTERNAL_OBSERVER_KEY

A unique identifier for a user with the system role of Observer at the institution. This ID is provided bythe institution and is not displayed to users. String. Max length 64. Multi-byte characters accepted.Not Null, External Key

EXTERNAL_USER_KEY

A unique identifier for a user with the Institution Role of Student at the institution. This ID is providedby the institution and is not displayed to users. String. Max length 64. Multi-byte characters accepted.Not Null, External Key

OBSERVER_MEMBERSHIP

The observer membership.

INERNAL_ID The internal identification for the observer.

INTERNAL_OBSERVER_ID

Defines the internal observer identification.

INTERNAL_USER_ID

The internal user identification for the observer.

USER_ELEMENT

User Data Feed ElementsThe following fields must be present in a user record for it to be successfully processed:


9.1 S

P6 BETA D

RAFT


l EXTERNAL_PERSON_KEYl USER_IDl SYSTEM_ROLEl FIRSTNAMEl LASTNAMEl EMAILl INSTITUTION_ROLE


SYSTEM_ROLE The user’s administrative role, describing the user’s level of system administration privilege.The role of “none” has no system administration or Course creation privileges associated withit, and is the most commonly assigned role. The following strings are acceptable:

l User Administrator: "account_admin", "accountadmin" or "user_admin"l System Support: "system_support" or "syssupport"l Course Creator: "course_creator" or "creator"l Support: "course_support" or "support"l Guest: "guest"l None: "none"l Observer: "observer"l Portal Administrator: "portal_admin" or "portal"l System Administrator: "sys_admin", "sysadmin" or "system_admin"l eCommerce Administrator: "ecommerce_admin"l Card Office Administrator: "card_office_admin"l Store Administrator: "store_admin"l User defined system roles can be used. Just match the “Role ID” found in

Administrator Panel > System RoleIf one is not given the system defaults to none.

EXTERNAL_PERSON_KEY

A unique identifier for a user at the institution. This ID is provided by the institution and is notdisplayed to users. It is strongly recommended that the key data be a permanent, non-changing identifier for each user. An example of a good key is a permanent Student IDassigned when the person applies to the institution. The database cannot merge data betweendistinct accounts. String. Max length 64. Multi-byte characters accepted. Not Null, External Key

NEW_EXTERNAL_PERSON_KEY

This field is used only on the rare occasions when a user’s EXTERNAL_PERSON_KEYchanges. String. Max length 64. Multi-byte characters accepted.

COMPANY The name of the company for which the user works. String. Max length 100. Multi-bytecharacters accepted.

USERNAME The username used to log into Blackboard Learn. The user name must be unique. String. Maxlength 50. Multi-byte characters accepted. Not Null

PASSWORD The password used to log into Blackboard Learn. On insert, if a password is not included, thanthe password defaults to the username (Unless it is “not owned” by the institution). Must besent MD5 encoded if the encrypt.password property is set to N. String. Max length 32. Multi-byte characters accepted. If Multi-byte characters are included, the encrypt.password propertymust be set to Y.

STUDENT_ID Generic identifier field. This is a display only field. String. Max length 100. Multi-byte charactersaccepted.

EMAIL The email address of the user. Blackboard recommends that user_email is not null. Userswithout an email address cannot send email. String. Max length 100

STREET_1 The first line of the address of the user. String. Max length 100. Multi-byte characters accepted.


9.1 S

P6 BETA D

RAFT



STREET_2 The second line of the address of the user. String. Max length 100. Multi-byte charactersaccepted.

GENDER The gender of the user. Passed as a string. (“Not Disclosed”, “Male”, “Female”)

BIRTH_DATE The user’s birth date in yyyy-mm-dd format. Date

TITLE The title that the user prefers to use. String. Max length 100. Multi-byte characters accepted.

CITY The city name corresponding to the user’s address. String. Max length 50. Multi-bytecharacters accepted.

STATE The state or province name corresponding to the user’s address. String. Max length 50. Multi-byte characters accepted.

ZIP_CODE The user’s ZIP or Postal Code. String. Max length 50. Multi-byte characters accepted.

DEPARTMENT The name of the department or sub-section where the user works. String. Max length 100.Multi-byte characters accepted.

COUNTRY The country name corresponding to the user’s address. String. Max length 50. Multi-bytecharacters accepted.

B_PHONE_1 The work phone number associated with the user. String. Max length 50. Multi-byte charactersaccepted.

B_PHONE_2 An additional work phone number associated with the user. String. Max length 50. Multi-bytecharacters accepted.

FIRSTNAME The user’s given first name. String. Max length 100. Multi-byte characters accepted. Not null

H_FAX The user’s home fax number. String. Max length 50. Multi-byte characters accepted.

B_FAX The work fax number associated with the user. String. Max length 50. Multi-byte charactersaccepted.

H_PHONE_1 The user’s home phone number. String. Max length 50. Multi-byte characters accepted.

H_PHONE_2 An additional home phone number associated with the user. String. Max length 50. Multi-bytecharacters accepted.

M_PHONE The user’s mobile phone or pager number. String. Max length 50. Multi-byte charactersaccepted.

JOB_TITLE The associated job title for the user. String. Max length 100. Multi-byte characters accepted.

PUBLIC_INDICATOR

Determines if the user’s personal information will be displayed in the User Directory. Valuesmay be “Y” for yes, or “N” for no. Char(1). Y/N

AVAILABLE_IND User account availability within the user interface. If set to no, the user account will appear ingray to the Administrator and Instructors. The user will not be able to log into the system.Values may be “Y” for yes, or “N” for no. Char(1). Y/N

ADDRESS_INDICATOR

Determines if the user’s home address will be displayed in the User Directory. Values may be“Y” for yes, or “N” for no. If a value is not provided the default is no. Char(1). Y/N

EMAIL_INDICATOR Determines if the user’s email address will be displayed in the User Directory. Values may be“Y” for yes, or “N” for no. If a value is not provided the default is no. Char(1). Y/N

PHONE_IND Determines if home phone, fax or cell phone numbers will be displayed in the User Directory.Values may be “Y” for yes, or “N” for no. If a value is not provided the default is no. Char(1). Y/N

WORK_INDICATOR Determines if work contact information (company, department, title, phone, fax) will bedisplayed in the User Directory. Values may be “Y” for yes, or “N” for no. If a value is notprovided the default is no. Char(1). Y/N

LASTNAME The user’s family/last name. String. Max length 100. Multi-byte characters accepted. Not null


9.1 S

P6 BETA D

RAFT



MIDDLE_NAME The user's given middle name. String. Max length 100. Multi-byte characters accepted.

X_INSTITUTION_ROLE

The user’s Primary Institution Role, which determines the user’s view of the Portal Modulesand other items. Passed as a string. See "Manage Institution Roles" in the System Admin panelfor the list of valid Institution Roles on the system.

ROW_STATUS Sets the value of the record to one of the following: Enabled: Normal access to the record.Disabled: Record is visible in some areas of the UI, but may not be changed or accessed.Deleted: Record is scheduled to be removed. Passed as a string. (“enabled”, “disabled”,“deleted”)

EDUCATION_LEVEL The highest level of education achieved by the user. Passed as a string. (“K-8”, “high school”,“freshman”, “sophomore”, “junior”, “senior”, “graduate school”, “post-graduate school”)

WEB_PAGE The URL of the user’s personal Web page, if they have one. String. Max length 100

NEW_DATA_SOURCE_KEY

Key used to establish grouping of user elements. Passed as a string. Multi-byte charactersaccepted.

CARD_NUMBER Identifier for a Campus Card used with the Blackboard Transaction System. Passed as a stringor as an encrypted string depending on the encrypt.card.number property.

LOCALE Identifier for the user's preferred language pack. The value is expressed as xx_XX, forexample, the French language pack is represented by fr_FR.

ADDRESS The associated address for the user.

CONTACT_INDICATOR

DEMOGRAPHICS The demographics for the user.

ENCRYPTION_TYPE

FAMILY_NAME The family name for the user. This is also considered the last name.

GIVEN_NAME The given name for the user. This is also considered the first name.

INSTITUTION_ROLE

The institution role for the user.

INSTITUTION_ROLE_TYPE

The institution role type for the user.

INTERNAL_ID The user's internal identification.

N_ELEMENT

NAME An additional name field for the user's name.

OTHER_NAME An additional name field for the user's name, typically used for the middle name.

PERSON

PRIMARY_INSTITUTION_ROLE

The user's primary institution role.

SETTINGS The user's settings.

SYSTEM_ROLE_TYPE

The user's system role type.

SUFFIX The suffix for the user's name.

SZ_PORTAL_ROLE

TELEPHONE The telephone number for the user.

TELEPHONE_TYPE The type of telephone number for the user.


9.1 S

P6 BETA D

RAFT



X_PASSWORD The user's password.

X_SYSTEM_ROLE The user's system role.

X_LMSINTEGRATION_ROLE

User Institution Role Membership Data Feed ElementsTomatch a user to multiple Institution Roles requires multiple records in the file.

The following table outlines the fields included in a record in a Snapshot User Institution RoleMembership file.

Element Description

EXTERNAL_PERSON_KEY

A unique identifier for a user at the institution This ID is provided by the institution and is notdisplayed to users. String. Max length 64. Multi-byte characters accepted.Not Null, External Key

ROLE_ID Institution Role. See "Manage Institution Roles" in the System Admin panel for the list of validInstitution Roles on the system.Passed as a string. Not null. Multi-byte characters accepted.

PORTAL_ROLE_MEMBERSHIP

ROLE The role name.

ROLE_TYPE The role type.

XML

Data Format Tables for XML Files

Data TablesEach of the topics that cover data feed formats contains detailed tables that describe each data attribute. Thefollowing columns appear in the data feed attribute tables:

l XML Construction the XML hierarchy that defines each piece of data.l Description and Data Type the definition of the data and the formatting. Beginning with Blackboard

Learn (Release 7.0) certain elements accept Multi-byte characters. These are noted in the tablesbelow.

IMS StandardXML files processed by Snapshot conform to the IMS standard. Additional data, specific only to BlackboardLearn, is handled by extending the IMS standard with the element <EXTENSION>. Blackboard supports boththe IMS 1.0.92 and themore recent IMS 1.1 standard.

To learnmore about the IMS Standard, see http://www.imsglobal.org.

How to Create an XML File for SnapshotBegin the XML file with the <ENTERPRISE> element. It is possible to include different data types, such asCourse data, user data, and category membership data in the same XML file.

Begin by encapsulating each item with one of the following sets of tags:


9.1 S

P6 BETA D

RAFT

http://www.imsglobal.org/


l User: <PERSON></PERSON>l Secondary Role Student: <PORTAL_ROLE_MEMBERSHIP></PORTAL_ROLE_MEMBERSHIP>l Course or Organization: <GROUP></GROUP>l CourseMembership or OrganizationMembership: <MEMBERSHIP></MEMBERSHIP>l Course Category or Organization Category: <CATEGORY>l Course Category Membership or Organization Category Membership: <CATEGORY_MEMBERSHIP></CATEGORY_MEMBERSHIP>

Category Data <CATEGORY>

XML Construction Description

<SOURCEDID> <ID> Must be unique. This field corresponds to the Category Mnemonic field in the UI. Not null.String. Max length 64. Multi-byte characters accepted.

<EXTENSION> <X_BB_ROW_STATUS>

The following numeric values set the record state to: 0 - Enabled: Normal access to therecord. 1 - Disabled: Record is visible in some areas of the UI, but may not be changed oraccessed. 2 - Deleted: Record is scheduled to be removed.

<EXTENSION> <X_BB_AVAILABLE_INDICATOR>

Establishes category availability within Blackboard Learn. Char(1). Y/N

<EXTENSION> <X_BB_TITLE>

The name of the category as it will appear to users within the UI. String. Max length 255.Multi-byte characters accepted.

<EXTENSION> <X_BB_FRONTPAGE_INDICATOR>

Determines whether or not the category is displayed on the front page of the catalog.Char(1). Y/N

<EXTENSION> <X_BB_DATASOURCE_KEY>

Key used to establish grouping of category elements. String based key. Multi-bytecharacters accepted.

<EXTENSION> <X_BB_PARENT_KEY>

Identifies the parent category in the category tree. String based key. Multi-byte charactersaccepted.

<EXTENSION> <X_BB_REPLACEMENTKEY>

Designates replacement for the current key. String. Max length 64. Multi-byte charactersaccepted.

<CATEGORY> The category name.

<X_BB_DESCRIPTION>

The category description.

<X_BB_INTERNAL_ID>

The internal category ID.

<X_BB_INTERNAL_PARENT_ID>

The internal parent category ID.

<X_BB_RESTRICT_INDICATOR>

<TYPE> The node type.


9.1 S

P6 BETA D

RAFT


Category Membership Data <CATEGORY_MEMBERSHIP>

XMLConstruction Description

<MEMBER><SOURCEDID><ID>

String. Max length 64. Not null. Multi-byte characters accepted.

<SOURCEDID><ID>

Internal numeric Id. Not null. Multi-byte characters accepted.

<EXTENSION><X_BB_ROW_STATUS>

Sets the value of the record to one of the following: Enabled: Normal access to the record.Disabled: Record is visible in some areas of the UI, but may not be changed or accessed.Deleted: Record is scheduled to be removed. Passed as a string. (enabled, disabled, deleted)

<EXTENSION><X_BB_AVAILABLE_INDICATOR>

Establishes the Category Membership availability within Blackboard Learn. Char(1). Y/N

<EXTENSION><X_BB_DATASOURCE_KEY>

Designates replacement for the current key. String. Max length 64. Multi-byte charactersaccepted.

<CATEGORY_MEMBERSHIP>

Defines the category membership.

<X_BB_INTERNAL_ID>

The internal category membership ID.

<X_BB_CATEGORY_ID>

The category membership ID.

<X_GROUP_ID> The internal group ID.

<CATEGORY_MEMBER>

Defines the category member.

<TYPE> Node type.


9.1 S

P6 BETA D

RAFT


Course and Organization Data <GROUP>

XML Element Description

<DESCRIPTION><SHORT>

Short name used by the institution to uniquely identify the Course (for example, math101 _F99). The following characters may not be used in Course ID: " ()& / ' + "Not null String. Max length 50. Must be unique and cannot be changed.

<SOURCEDID> <ID> Short name used by the Institution to uniquely identify the Course section. This is notdisplayed to users.Can contain only letters, digits, dashes and periods. No spaces or other punctuationallowed. May be concatenation of Course_ID, Section_ID, and Term. Must be unique foreach Course, and is often the same as the COURSE_ID.Not null, External key. String. Max length 64. Must be unique. Multi-byte charactersaccepted.


This field is used only on the rare occasions when a Courses EXTERNAL_COURSE_KEYchanges.String. Max length 64. Must be unique. Multi-byte characters accepted.

<DESCRIPTION><LONG>

Complete title of the Course. The Course Name is used when sorting.String. Max length 255. Multi-byte characters accepted.Not null

<X_BB_ALLOW_GUESTS>

Allows guest access to the Course.String. y/n

<DESCRIPTION><FULL>

Complete description of the Course.String. Max length 4000. Multi-byte characters accepted.

<TIMEFRAME> <END> Date on which access to the Course ends.Date (yyyy-mm-dd).

<TIMEFRAME><BEGIN>

Date on which access to the Course section begins.Date (yyyy-mm-dd).


Key used to establish a grouping of Course or Organization elements.String. Multi-byte characters accepted.


The following numeric values set the record state to:0 - Enabled: Normal access to the record.

1 - Soft Delete: Record is not visible in the UI, but has not been removed.2 - Disabled: Record is visible in some areas of the UI, but may not be changed oraccessed.3 - Delete Pending: Record is scheduled to be removed.

4 - Copy Pending: Record is scheduled to be copied.

<EXTENSION> <X_BB_AVAILABLE>

Establishes Course or Organization availability to Blackboard Learn.Char(1). Y/N

<EXTENSION> <X_BB_CATALOG>

Establishes whether the Course or Organization appears in catalog.Char(1). Y/N

<EXTENSION> <X_BB_DESCRIPTION_PAGE>

Determines whether or not to display description information in the Course orOrganization catalog.Char(1). Y/N

<EXTENSION> <X_BB_LOCKOUT_INDICATOR>

Indicates if access to the Course or Organization has been restricted. If set to Y access tothe Course or Organization will be restricted based on the END_DATE and START_DATE.Char(1). Y/N

<EXTENSION> <X_BB_PACE>

Indicates if the Course is Instructor-paced according to the Student.Char(1). Mapping accepted {Instructor}


9.1 S

P6 BETA D

RAFT



<EXTENSION> <X_BB_ENROLL_START>

Date that enrollment may begin.Date (yyyy-mm-dd).

<EXTENSION> <X_BB_ENROLL_END>

Date that enrollment is no longer available to Students.Date (yyyy-mm-dd).

<EXTENSION> <X_BB_ENROLLMENT_TYPE>

The following numeric values set the enrollment method:0 - Instructor1 - Self Enrollment

<EXTENSION> <X_BB_DAYS_OF_USE>

Number of days that Students may access the Course after enrollment. Useful for self-paced learning.Numeric.

<EXTENSION> <X_BB_DURATION>

The following numeric values set the schedule enrollment window:0 - Continuous: The Course is always accessible.1 - Date Range: The Course is accessible in the days between one date and another.Either the beginning date or the end date can be left open-ended to make a Courseaccessible from a certain date or until a certain date.2 - Fixed Number of Days: The Course is accessible for a set number of days.

<EXTENSION> <X_BB_INSTITUTION_NAME>

The name of the institution.String. Max length 255. Multi-byte characters accepted.

<EXTENSION> <X_BB_CLASSIFICATIONKEY>

Sting-based key that establishes an association with a subject area and discipline withinthe Blackboard Resource Center.

<EXTENSION> <X_BB_TEMPLATEKEY>

Designates content source for copy operation.String. Max length 64. . Multi-byte characters accepted.

<EXTENSION><GROUPTYPE>

The following numeric values set the group type:0 - Course1 - Organization

<EXTENSION> <X_BB_LOCALE>

Identifier for the Course language pack. The value is expressed as xx_FR, for example,the French language pack is represented by fr_FR.

<EXTENSION> <X_BB_LOCALE_ENFORCED_INDICATOR>

A Y/N flag that determines if the language pack is enforced when a user accesses theCourse. If the language pack is not enforced, the user may view the Course using theirpreferred language pack.

<GROUP> The admin course group.

<X_BB_ALLOW_ENROLL>

Allow enrollment.

<X_BB_ALLOW_OBSERVERS>

Allow observers.

<COURSE_STD_SUB_DOC_ASSOCIATIONS>

Course document associations.

<X_BB_CONTENT_PACKAGE>

Content package.

<X_BB_ENROLLMENT_ACCESS_CODE>

The enrollment access code.

<X_BB_FEE> Designates a fee.

<X_BB_INTERNAL_ID> The internal identification.

<X_BB_INTERNAL_CLASSIFICATION_ID>

The internal classification identification.

<X_BB_INTERNAL_BUTTONSTYLES_ID>

The internal button styles identification.


9.1 S

P6 BETA D

RAFT



<X_BB_LMS_INTEGRATION>

Designates LMS integration.

<X_BB_PROXY_INDICATOR>

Proxy indicator.

<X_BB_NAVSTYLE> Navigation style.

<RESTRICT> Restrictions.

<TYPEVALUE> Service Level.

<SUB_DOC_BATCH_UID>

<TIMEFRAME>

<X_LMS_COPY_IMS_SOURCE>

<X_LMS_COPY_IMS_ID>

<XPROXY> LMS proxy.


9.1 S

P6 BETA D

RAFT


Enrollment and Staff Students Data <MEMBERSHIP>

XML Element Description and Data Type

<SOURCEDID> <ID> Used to look up appropriate keys. This is the same key used to identify the Courseor Organization.This is the same key as the Course.Not Null, external key. Multi-byte characters accepted.

<MEMBER> <SOURCEDID><ID>

Used to look up appropriate keys. This is the same key used to identify the user.Not Null, external key. Multi-byte characters accepted.

<MEMBER> <ROLEroletype="4">

The users role in the Course. String. This value is mapped to a one characterdatabase constant. The valid values are:0 - None1 - Student2 - Instructor3 - Course Builder6 - Teaching Assistant8 - Grader9 - GuestThe system assumes that any other value is a custom role identifier.

<MEMBER> <ROLE><STATUS>

The following numeric values set the record state to:0 - Enabled: Normal access to the record.1 - Disabled: Record is visible in some areas of the UI, but may not be changed oraccessed.2 - Deleted: Record is scheduled to be removed.

<EXTENSION> <BB_REPLACEMENTKEY>

Establishes enrollment availability in Blackboard Learn.Char(1). Y/N


Key used to establish grouping of enrollment elements.Multi-byte characters accepted.

<X_BB_HAS_CARTRIDGE_ACCESS>

Defines common course cartridge access.

<X_BB_ENROLLMENT_DATE> The enrollment date.

<X_BB_INCLUDED_IN_ROSTER>

Defines inclusion to the roster.

<X_BB_INTRODUCTION> The introduction.

<X_BB_INTERNAL_ID> Internal identification.

<X_BB_INTERNAL_GROUP_ID>

Internal group identification.

<X_BB_INTERNAL_PERSON_ID>

Internal person identification.

<X_BB_LAST_ACCESS_DATE> The date last accessed.

<X_BB_LINK_NAME_1> Link name.

<X_BB_LINK_DESC_1> Link description.

<X_BB_LINK_URL_1> Link URL.






9.1 S

P6 BETA D

RAFT


XML Element Description and Data Type



<MEMBER>

<MEMBERSHIP> Defines membership.

<X_BB_NOTES>

<X_BB_PRIVATE_INFORMATION>

<X_BB_RECEIVE_EMAIL> Sets the ability to receive email.

<ROLETYPE> Defines the role type.

<IDTYPE> Defines the identification type.

<X_BB_INHERITEDMEMBERSHIP>

Inherit membership from WebCT.


9.1 S

P6 BETA D

RAFT


XML User Data <PERSON>


<EXTENSION> <X_BB_SYSTEMROLE>

The user's administrative role, describing the user's level of system administrationprivilege. The role of none has no system administration or Course creation privilegesassociated with it, and is the most commonly assigned role.The following numeric values are acceptable:0 – System Administrator1 – System Support2 – Course Creator3 – Account Administrator4 – None5 – Course Support6 – User7 – Observer8 – Guest9 – Integration (No GUI access)10 – Portal Administrator11 – eCommerce Administrator12 – Card Office Administrator13 – eMarketplace AdministratorIf one is not given the system defaults to none.

<SOURCEDID> <ID> A unique identifier for a user at the Institution This ID is provided by the Institution and isnot displayed to users.Blackboard strongly recommends that the key data be a permanent, non-changingidentifier for each user. An example of a good key is a permanent Student ID assignedwhen the person applies to the Institution. The database cannot merge data betweendistinct accounts.String. Max length 64. Multi-byte characters accepted.Not Null, External Key


This field is used only on the rare occasions when a users EXTERNAL_PERSON_KEYchanges.String. Max length 64. Multi-byte characters accepted.

n/a The name of the company for which the user works.String. Max length 100. Multi-byte characters accepted.

<SOURCEDID> <USERID> The username used to log into Blackboard Learn. The user name must be unique.String. Max length 50. Multi-byte characters accepted.Not Null

<EXTENSION> <X_BB_PASSWORD>

The password used to log into Blackboard Learn. On insert, if a password is notincluded, the password defaults to the username (Unless it is not owned by theInstitution).Must be sent MD5 encoded if the encrypt.password property is set to N. The Snapshotcontroller available with Blackboard Learn is set to handle MD5 encryption.String. Max length 32. Multi-byte characters accepted. If Multi-byte characters are used,the encrypt.password property must be set to N.The IMS 1.1 standard uses <USERID password= > to express a password.

<EXTENSION> <X_BB_StudentID>

Generic identifier field. This is a display only field.String. Max length 100. Multi-byte characters accepted.

<EMAIL> The email address of the user. Blackboard recommends that user_email is not null.Sending email without the From field populated can cause problems.String. Max length 100

<ADR> <STREET> The first line of the address of the user.String. Max length 100. Multi-byte characters accepted.


9.1 S

P6 BETA D

RAFT



<ADR> <STREET> The second line of the address of the user.String. Max length 100. Multi-byte characters accepted.

<DEMOGRAPHICS><GENDER>

The gender of the user.0 - unknown1 - female2 - male

<DEMOGRAPHICS> <BDAY> The users birth date in yyyymmdd format.Date

<NAME> <N> <PREFIX> The title that the user prefers to use.String. Max length 100. Multi-byte characters accepted.

<ADR> <LOCALITY> The city name corresponding to the users address.String. Max length 50. Multi-byte characters accepted.

<ADR> <REGION> The state or province name corresponding to the user's address.String. Max length 50. Multi-byte characters accepted.

<ADR> <PCODE> The users ZIP or Postal Code.String. Max length 50. Multi-byte characters accepted.

n/a The name of the department or sub-section where the user works.String. Max length 100. Multi-byte characters accepted.

<ADR> <COUNTRY> The country name corresponding to the user's address.String. Max length 50. Multi-byte characters accepted.

<TEL> <TELteletype="0">

The phone number associated with the user. The following numeric values areacceptable for teletype:0 - Home phone1 - Home fax2 - Work phone3 - Work fax4 - Mobile phone5 - Home phone (secondary)6 - Work phone (secondary)String. Max length 50. Multi-byte characters accepted.

<NAME> <N> <GIVEN> The users given first name.String. Max length 100Not null. Multi-byte characters accepted.

<EXTENSION> <X_BB_PUBLIC_INDICATOR>

Determines if the users personal information will be displayed in the User Directory.Values may be Y for yes, or N for no.Char(1). Y/N

<EXTENSION> <X_BB_AVAILABLE>

User account availability within the user interface. If set to no, the user account willappear in gray to the Administrator and Instructors. The user will not be able to log intothe system. Values may be Y for yes, or N for no.Char(1). Y/N

<EXTENSION> <X_BB_ADDRESS_INDICATOR>

Determines if the user's home address will be displayed in the User Directory. Valuesmay be Y for yes, or N for no. If a value is not provided the default is no.Char(1). Y/N

<EXTENSION> <X_BB_EMAIL_INDICATOR>

Determines if the user's email address will be displayed in the User Directory.Values may be Y for yes, or N for no. If a value is not provided tvChar(1). Y/N


9.1 S

P6 BETA D

RAFT



<EXTENSION> <X_BB_CONTACT_INDICATOR>

Determines if home phone, fax or cell phone numbers will be displayed in the UserDirectory.Values may be Y for yes, or N for no. If a value is not provided the default is no.Char(1). Y/N

<EXTENSION> <X_BB_WORK_INDICATOR>

Determines if work contact information (company, department, title, phone, fax) will bedisplayed in the User Directory. Values may be Y for yes, or N for no. If a value is notprovided the default is no.Char(1). Y/N

<NAME> <N> <OTHER> The user's given middle name.String. Max length 100. Multi-byte characters accepted.

<EXTENSION> <X_BB_INSTITUTION_ROLE>

The user's Primary Institution Role, which determines the user's view of the PortalModules and Academic Web Resources.The following numeric values represent a role:0 - Student1 - Faculty2 - Staff3 - Alumni4 - Prospective Student5 - Guest6 - Other7 - Observer9 through 20 - additional default rolesThe IMS 1.1 standard supports the <INSTITUTIONROLE> element.


The following numeric values set the record state to:0 - Enabled: Normal access to the record.1 - Disabled: Record is visible in some areas of the UI, but may not be changed oraccessed.2 - Deleted: Record is scheduled to be removed.


Key used to establish grouping of user elements.Passed as a string. Multi-byte characters accepted.

<EXTENSION> <X_BB_CARD_NUMBER>

Identifier for a Campus Card used with Blackboard Transact.Passed as a string or as an encrypted string depending on the encrypt.card.numberproperty.

<EXTENSION> <X_BB_LOCALE>

Identifier for the preferred user language pack. The value is expressed as xx_XX, forexample, the French language pack is represented by fr_FR.

<ADR> The user's address.

<X_BB_COMPANY> The company name.

<DEMOGRAPHICS> Demographics of the user.

<X_BB_COMPANY_DEPARTMENT>

The user's department.

<X_BB_EDUCATION_LEVEL>

The user's education level.

<PWENCRYPTIONTYPE> The type of password encryption on the user's account.

<FAMILY> The family name of the user. This is also considered the user's last name.

<INSTITUTIONROLE> The user's institution role.

<INSTITUTIONROLETYPE> The user's institution role type.

<X_BB_INTERNAL_ID> The user's internal identification.

<X_BB_JOB_TITLE> The user's job title.


9.1 S

P6 BETA D

RAFT



<N>

<NAME> A field used for part of the user's name.

<OTHER> A field which can be used for the user's middle name.

<PASSWORD> The user's password.

<PERSON>

<PRIMARYROLE> The user's primary institution role.

<X_BB_SETTINGS> The user's settings.

<SYSTEMROLE> The user's system role.

<SYSTEMROLETYPE> The user's system role type.

<SUFFIX> A field which can be used for the user's name suffix.

<X_BB_PORTALROLE>

<TEL> The user's telephone number.

<X_BB_WEBPAGE> The user's web page.

<X_BB_LMSINTEGRATION_ROLE>

The user's LMS integration role.

XML User Data Secondary Institutional Role <PORTAL_ROLE_MEMBERSHIP>

XMLConstruction Description

<SOURCEDID><ID>

A unique identifier for a user at the Institution This ID is provided by the Institution and is notdisplayed to users. It is strongly recommended that the key data be a permanent, non-changingidentifier for each user. An example of a good key is a permanent Student ID assigned when theperson applies to the Institution. The database cannot merge data between distinct accounts.String. Max length 64. Multi-byte characters accepted. Not Null, External Key

<ROLE> <ROLEroletype="4”>

The user's role in the Course.String. The value is mapped to a database constant. The valid values are:0 - Student1 - Faculty2 - Staff3 - Alumni4 - Prospective Student5 - Guest6 - Other7 - Observer9

20 - Custom role identifiers

Secondary Institution Roles may not be added to other User XML feeds. Each additional secondary role musthave its own independent feed file. The Secondary Institution Role should not be the same as the PrimaryInstitution Role.


9.1 S

P6 BETA D

RAFT

Resources > Samples

Samples

Sample Code for Clean Up of Database Bound ObjectsUse this code sample as the basis for clean up of database bound objects for event driven APIs.

Event Driven API - Clean up of database bound objectstry

{

crsCatMemPersister.remove(crs_cat_mem);

}

catch(Exception exc){}

try

{

orgCatMemPersister.remove(org_cat_mem);

}


try

{

crsCatPersister.remove(crs_cat);

}


try

{

orgCatPersister.remove(org_cat);

}


try

{

ePersister.remove(enroll);

}


try

{

orgMemPersister.remove(orgmem);

}


try

{

saPersister.remove(staff);

}



9.1 S

P6 BETA D

RAFT

Resources > Samples

try

{

pPersister.remove(person_1);

}


try

{


}


try

{

cPersister.remove(course);

}

catch(Exception exc)

{

}

try

{

orgPersister.remove(org);

}

catch(Exception exc)

{

}

Sample Code to Create Data ObjectsUse this code sample as a basis to create data objects for Event Driven APIs.

Event Driven API - Data Object creationblackboard.admin.data.user.Person person_1 = new blackboard.admin.data.user.Person();

blackboard.admin.data.user.Person person_2 = new blackboard.admin.data.user.Person();

blackboard.admin.data.course.Coursesite course = newblackboard.admin.data.course.Coursesite();

blackboard.admin.data.course.Organization org = newblackboard.admin.data.course.Organization();

blackboard.admin.data.course.Enrollment enroll = newblackboard.admin.data.course.Enrollment();

blackboard.admin.data.course.OrganizationMembership orgmem = newblackboard.admin.data.course.OrganizationMembership();

blackboard.admin.data.course.StaffStudent staff = newblackboard.admin.data.course.StaffStudent();

blackboard.admin.data.category.CourseCategory crs_cat = newblackboard.admin.data.category.CourseCategory();

blackboard.admin.data.category.OrganizationCategory org_cat = newblackboard.admin.data.category.OrganizationCategory();

blackboard.admin.data.category.CourseCategoryMembership crs_cat_mem = newblackboard.admin.data.category.CourseCategoryMembership();


9.1 S

P6 BETA D

RAFT

Resources > Samples

blackboard.admin.data.category.OrganizationCategoryMembership org_cat_mem = newblackboard.admin.data.category.OrganizationCategoryMembership();

Sample Code for Data Object Attribute MarshallingUse this code sample as the basis for data object attributemarshalling for event driven APIs.

Event Driven API - Data Object attribute marshallingperson_1.setDataSourceBatchUid("SIS");

person_1.setEmailAddress("[email protected]");

person_1.setFamilyName("Baal");

person_1.setGivenName("Hannibal");

person_1.setBatchUid("33333");

person_1.setPassword("hbaal");

person_1.setUserName("hbaal");

person_1.setSystemRole( person_1.SystemRole.SYSTEM_ADMIN);

person_1.setTitle("General");

person_2.setDataSourceBatchUid("SIS");

person_2.setEmailAddress("[email protected]");

person_2.setFamilyName("Hun");

person_2.setGivenName("Atillah");

person_2.setBatchUid("11111");

person_2.setPassword("ahun");

person_2.setUserName("ahun");

person_2.setSystemRole( person_2.SystemRole.SYSTEM_ADMIN);

person_2.setTitle("General");

course.setCourseId("CRTHG101_CRS");

course.setDataSourceBatchUid("SIS");

course.setBatchUid("ACRTHG101_CRS");

course.setTitle("Intimidation through Mammoths");

course.setInstitutionName("Carthage");

course.setDescription("Discussion of the use ");

org.setOrganizationId("CRTHG101_ORG");

org.setDataSourceBatchUid("SIS");

org.setBatchUid("ACRTHG101_ORG");

org.setTitle("Intimidation through Mammoths");

org.setInstitutionName("Carthage");

org.setDescription("Discussion of the use ");

enroll.setDataSourceBatchUid("SIS");

enroll.setCourseSiteBatchUid("ACRTHG101_CRS");

enroll.setPersonBatchUid("33333");


9.1 S

P6 BETA D

RAFT

Resources > Samples

staff.setDataSourceBatchUid("SIS");

staff.seCourseSiteBatchUid("ACRTHG101_CRS");

staff.setPersonBatchUid("11111");

staff.setRole( staff.Role.Student" /> );

orgmem.setDataSourceBatchUid("SIS");

orgmem.setOrganizationBatchUid("ACRTHG101_ORG");

orgmem.setPersonBatchUid("33333");

orgmem.setRole( staff.Role.INSTRUCTOR);

crs_cat.setBatchUid("ACRTHGCAT");

crs_cat.setDataSourceBatchUid("SIS");

crs_cat.setFrontPageInd(true);

crs_cat.setIsAvailable(true);

crs_cat.setTitle("Carthage Course Category");

org_cat.setBatchUid("ACRTHGCAT");

org_cat.setDataSourceBatchUid("SIS");

org_cat.setFrontPageInd(true);

org_cat.setIsAvailable(true);

org_cat.setTitle("Carthage Organization Category");

org_cat_mem.setCategoryBatchUid("ACRTHGCAT");

org_cat_mem.setDataSourceBatchUid("SIS");

org_cat_mem.setOrganizationBatchUid("ACRTHG101_ORG");

org_cat_mem.setIsAvailable(true);

crs_cat_mem.setCategoryBatchUid("ACRTHGCAT");

crs_cat_mem.setDataSourceBatchUid("SIS");

crs_cat_mem.setCourseSiteBatchUid("ACRTHG101_CRS");

crs_cat_mem.setIsAvailable(true);

Sample Code to Start Course/Organization Copy TestingUse this code sample as the basis for Start Course / Organization copy testing for all areas for event drivenAPIs.

Event Driven API – start Course / Organization copy testing/*********** Begin testing **********/

blackboard.admin.data.course.CourseSite tgtCourse = newblackboard.admin.data.course.CourseSite();

blackboard.admin.data.course.Organization tgtOrg = newblackboard.admin.data.course.Organization();

blackboard.admin.persist.course.CloneConfig cfg = newblackboard.admin.persist.course.CloneConfig();


9.1 S

P6 BETA D

RAFT

Resources > Samples

cfg.includeArea( blackboard.admin.persist.course.CloneConfig.Area.ALL );

tgtCourse.setBatchUid(“tgt.course”);

tgtOrg.setBatchUid(“tgt.organization”);

try

{

cPersister.clone(course.getBatchUid(),tgtCourse.getBatchUid(), cfg);

orgPersister.clone(org.getBatchUid(),tgtOrg.getBatchUid(), cfg);

}

catch(PersistenceException nfe)

{

System.out.println("insert enrollment without supporting object(s) success!");

}








System.out.println("All removals successful (pre-existing)");

System.out.println("Success!");

End Persistence Test

Sample Code to Start Persistence TestingUse this code sample as the basis for start persistence testing for event driven APIs.

Event Driven API – start persistance testing/*********** Begin testing **********/

try

{

ePersister.insert(enroll);

}


{

System.out.println("insert enrollment without supporting object(s) success!");

}


9.1 S

P6 BETA D

RAFT

Resources > Samples

try

{

saPersister.insert(staff);

}


{

System.out.println("insert staff student without supporting object(s) success!");

}

try

{

orgMemPersister.insert(orgmem);

}


{

System.out.println("insert organization membership without supporting object(s)success!");

}

try

{

orgCatMemPersister.insert(org_cat_mem);

}


{

System.out.println("insert organization link without supporting object(s) success!");

}

try

{

crsCatMemPersister.insert(crs_cat_mem);

}


{

System.out.println("insert course creation wizard without supporting object(s)success!");

}

try

{

ePersister.save(enroll);

}


{

System.out.println("save enrollment without supporting object(s) success!");

}


9.1 S

P6 BETA D

RAFT

Resources > Samples

try

{

saPersister.save(staff);

}


{

System.out.println("save staff assignment without supporting object(s) success!");

}

try

{

orgMemPersister.save(orgmem);

}


{

System.out.println("save organization membership without supporting object(s)success!");

}

try

{

orgCatMemPersister.save(org_cat_mem);

}


{

System.out.println("save organization link without supporting object(s) success!");

}

try

{

crsCatMemPersister.save(crs_cat_mem);

}


{

System.out.println("save course creation wizard without supporting object(s) success!");

}

try

{

pPersister.update(person_1);

pPersister.update(person_2);

}


{


9.1 S

P6 BETA D

RAFT

Resources > Samples

System.out.println("Update not found success (Person)!");

}

try

{

cPersister.update(course);

}


{

System.out.println("Update not found success (Course)!");

}

try

{

orgPersister.update(org);

}


{

System.out.println("Update not found success (Organization)!");

}

try

{

ePersister.update(enroll);

}


{

System.out.println("update enrollment without supporting object(s) success!");

}

try

{

saPersister.update(staff);

}


{

System.out.println("update staff assignment without supporting object(s) success!");

}

try

{

orgMemPersister.update(orgmem);

}


{


9.1 S

P6 BETA D

RAFT

Resources > Samples

System.out.println("update organization membership without supporting object(s)success!");

}

try

{

crsCatPersister.update(crs_cat);

}


{

System.out.println("Update not found success (course Category)!");

}

try

{

orgCatPersister.update(org_cat);

}


{

System.out.println("Update not found success (organization Category)!");

}

try

{

orgCatMemPersister.update(org_cat_mem);

}


{

System.out.println("update organization link without supporting object(s) success!");

}

try

{

crsCatMemPersister.update(crs_cat_mem);

}


{

System.out.println("update course creation wizard without supporting object(s)success!");

}

cPersister.insert(course);

System.out.println("course insertion succeeded");

orgPersister.insert(org);


9.1 S

P6 BETA D

RAFT

Resources > Samples

System.out.println("organization insertion succeeded");

pPersister.insert(person_1);

System.out.println("person 1 insertion succeeded");

pPersister.insert(person_2);

System.out.println("person 2 insertion succeeded");

orgMemPersister.insert(orgmem);

System.out.println("org membership insertion succeeded");

saPersister.insert(staff);

System.out.println("staff student insertion succeeded");

ePersister.insert(enroll);

System.out.println("enrollment membership insertion succeeded");

crsCatPersister.insert(crs_cat);

System.out.println("course category insertion succeeded");

orgCatPersister.insert(org_cat);

System.out.println("organization category insertion succeeded");

crsCatMemPersister.insert(crs_cat_mem);

System.out.println("course creation wizard insertion succeeded");

orgCatMemPersister.insert(org_cat_mem);

System.out.println("organization link insertion succeeded");


System.out.println("enroll save succeeded");


System.out.println("staff save succeeded");


System.out.println("org membership save succeeded");

cPersister.save(course);

System.out.println("course save succeeded");

orgPersister.save(org);

System.out.println("organization save succeeded");

pPersister.save(person_1);


9.1 S

P6 BETA D

RAFT

Resources > Samples

System.out.println("person_1 save succeeded");


System.out.println("person_2 save succeeded");

crsCatPersister.save(crs_cat);

System.out.println("course category save succeeded");

orgCatPersister.save(org_cat);

System.out.println("organization category save succeeded");


System.out.println("course creation wizard save succeeded");


System.out.println("organization link save succeeded");


System.out.println("enroll remove succeeded");


System.out.println("staff remove succeeded");


System.out.println("org membership remove succeeded");


System.out.println("person 1 remove succeeded");


System.out.println("person 2 remove succeeded");


System.out.println("course creation wizard remove succeeded");


System.out.println("organization link remove succeeded");


System.out.println("course category remove succeeded");


System.out.println("organization category remove succeeded");



9.1 S

P6 BETA D

RAFT

Resources > Samples

System.out.println("course remove succeeded");


System.out.println("org remove succeeded");

try

{



}


{

System.out.println("Remove not found success (Person)!");

}

try

{


}


{

System.out.println("Remove not found success (Course)!");

}

try

{


}


{

System.out.println("Remove not found success (Organization)!");

}

try

{


}


{

System.out.println("Remove not found success (enroll)!");

}

try

{



9.1 S

P6 BETA D

RAFT

Resources > Samples

}


{

System.out.println("Remove not found success (staff)!");

}

try

{


}


{

System.out.println("Remove not found success (Org Membership)!");

}

try

{


}


{

System.out.println("Remove not found success (Course Category)!");

}

try

{


}


{

System.out.println("Remove not found success (Organization Category)!");

}

try

{


}


{

System.out.println("Remove not found success (course creation wizard)!");

}

try

{



9.1 S

P6 BETA D

RAFT

Resources > Samples

}


{

System.out.println("Remove not found success (organization link)!");

}



cPersister.save(course);

orgPersister.save(org);




crsCatPersister.save(crs_cat);

orgCatPersister.save(org_cat);



System.out.println("Save successful (non-existing)");

/******** Now beginning load test ***********************/

java.util.Iterator iter = null;

person_1 = pLoader.load(person_1.getBatchUid());

System.out.println("load of person 1 by batch uid successful");

person_2 = pLoader.load(person_2.getBatchUid());

System.out.println("load of person 2 by batch uid successful");

course = cLoader.load(course.getBatchUid());

System.out.println("load of course by batch uid successful");

org = orgLoader.load(org.getBatchUid());

System.out.println("load of org by batch uid successful");

enroll = eLoader.load(enroll.getCourseSiteBatchUid(), enroll.getPersonBatchUid() );

System.out.println("load of enroll by batch uid successful");

staff = saLoader.load( staff.getCourseSiteBatchUid(), staff.getPersonBatchUid() );

System.out.println("load of staff by batch uid successful");

orgmem = orgMemLoader.load( orgmem.getOrganizationBatchUid(),orgmem.getPersonBatchUid());

System.out.println("load of orgmem by batch uid successful");


9.1 S

P6 BETA D

RAFT

Resources > Samples

crs_cat = crsCatLoader.load(crs_cat.getBatchUid());

System.out.println("load of crs cat by batch uid successful");

org_cat = orgCatLoader.load(org_cat.getBatchUid());

System.out.println("load of org cat by batch uid successful");

org_cat_mem = orgCatMemLoader.load( org_cat_mem.getOrganizationBatchUid(), org_cat_mem.getCategoryBatchUid());

System.out.println("load of org cat mem by batch uid successful");

crs_cat_mem = crsCatMemLoader.load( crs_cat_mem.getCourseBatchUid(), crs_cat_mem.getCategoryBatchUid());

System.out.println("load of crs cat mem by batch uid successful");

BbList list = pLoader.load(person_1);

if ( list.size() == 1)

{

System.out.println("Load of person_1 successful");

}

else throw new Exception("person 1 load failed with " + list.size() + " count");

list = pLoader.load(person_2);


{

System.out.println("Load of person 2 successful");

}

else throw new Exception("person 2 load failed with " + list.size() + " count");

list = cLoader.load(course);


{

System.out.println("Load of course successful");

}

else throw new Exception("course load failed with " + list.size() + " count");

list = orgLoader.load(org);


{

System.out.println("Load of org successful");

}

else throw new Exception("org load failed with " + list.size() + " count");


9.1 S

P6 BETA D

RAFT

Resources > Samples

list = eLoader.load(enroll);


{

System.out.println("Load of enrollment successful");

}

else

{

System.out.println(enroll);

throw new Exception("enrollment load failed with " + list.size() + " count");

}

list = saLoader.load(staff);


{

System.out.println("Load of staff successful");

}

else throw new Exception("staff load failed with " + list.size() + " count");

list = orgMemLoader.load(orgmem);


{

System.out.println("Load of org membership successful");

}

else throw new Exception("org membership load failed with " + list.size() + " count");

list = crsCatMemLoader.load(crs_cat_mem);


{

System.out.println("Load of course creation wizard successful");

}

else throw new Exception("couse link load failed with " + list.size() + " count");

list = orgCatMemLoader.load(org_cat_mem);


{

System.out.println("Load of organization link successful");

}

else throw new Exception("organization link load failed with " + list.size() + " count");

list = crsCatLoader.load(crs_cat);



9.1 S

P6 BETA D

RAFT

Resources > Samples

{

System.out.println("Load of course category successful");

}

else throw new Exception("course category load failed with " + list.size() + " count");

list = orgCatLoader.load(org_cat);


{

System.out.println("Load of organization category successful");

}

else throw new Exception("organization category load failed with " + list.size() + "count");

/********************* End load test *************/





Sample Naming Convention for Data Source KeysIn order to ensure logical application and knowledge transfer, create a system for naming Data Source Keys sothat they can be easily identified. The following naming convention represents a relatively simple way to breakup the data sets to enable the twomost commonworkflows.

Data Source IDA simple ID should be assigned for the source system, for example SIS for a Student information system, orHRMS for a human resources management system. By combining this ID with an ID for each type of set, aflexible naming scheme can be derived to support typical workflows.

Type Bound SetsType bound sets include a component that is derived from the type of feed that is being performed. This way adata set is identified by the entities involved. For example, if the string ‘Course’ is used tomean “Course” thenthat string is included to indicate the type of the data set, for example SIS.COURSE.

Term Bound SetsTerm bound sets are used to group data that are related, but should not overlap time periods in the database.For example, it might be desirable to feed spring Courses into the database while fall Courses are still active.Using a key that distinguishes the two sets based on their term will prevent Snapshot operations on one setfrom interfering with data in the other. For example, SIS.SPRING2000 and SIS.FALL2000.

Type and Term Bound SetsIn many cases it is desirable to use a combination of type and term bound identification. Themost commonexample is Student enrollment at an institution with a fixed academic calendar—enrollment is bound to aspecific semester for example, SIS.COURSE.FALL2000.


9.1 S

P6 BETA D

RAFT

Resources > Samples

ExampleAn institution wants to process Student Students, Instructor lists, course section listings, and enrollments overthe course of several semesters. In general, from semester to semester, the Student and Instructor lists willencompass the same basic data set. However the Courses and enrollments will need to be processed on a per-semester basis. That is, from semester to semester, active Students and staff will be treated as a single logicalset (with fluid membership) while Courses and enrollments will be treated as logically distinct sets that do notintersect from semester to semester.

One solution is to use type-bound keys for Students and Instructors, and type and term bound keys for Coursesand enrollment. A Data Source Key is created called SIS.USERS that is used to identify the set of users overtime. By running Snapshot feeds on all ongoing users, all active Students, and staff may be processed as asingle set of data.

Separate Data Source Keys are created for Courses, enrollment, and instructor Students, all which are bothtype and term bound:SIS.COURSE.FALL2000

SIS.COURSE.SPRING2000

That way, all user feeds may use the SIS.USERS Data Source Key, while Courses and enrollment can use theSIS.COURSE.* keys, with guarantees that operations performed on one of the sets will not affect the other set.

As another example, different sets can be applied to different users:MEDSIS.USERS

SIS.USERS

ALUMNI.USERS

Illegal Characters for Data Source NamesData source keys should consist only of the letters A-Z, numbers 0-9, periods, and underscores (_).

Data Source Key names are not case sensitive.

Sample Properties File

Sample Properties File# Maximum errors to process.

# If you want all valid records to be processed, use -1 which indicates unlimited

# If you want an all or none transaction, use 0

# Otherwise, pick some reasonable number of errors

max.error.count=-1

# Snapshot process settings

# delimteter used for parsing snapshot files

data.delimeter=|

# Used to denote datasource to use for operation.

data.source.key=FALL_COURSES_05

# Determines if password field should be encrypted

encrypt.password=Y

# Determines if commerce card number attribute should be encrypted

encrypt.card.number=Y


9.1 S

P6 BETA D

RAFT

Resources > Samples

# Denotes string used to mark the beginning of errors

error.delimeter=(!)

# Determines character used to escape delimeter

escape.character=/

# Designates flag to handle header validation for configuration property file

header.validation=Y

# Determines if logged information should be sent to console.

log.stdout=N

# Designates flag to establish handling of enumerated values. To accept default or causean exception.

parse.allow.default=N

# Designates maximum size of database transaction

snapshot.batch.size=300

# Used to configure pause between persistence actions

wait.length=-1

# Snapshot controlled field settings for Blackboard override of data

# fields for category entities

category.bb.controlled.fields=

# fields for link entities

categorymembership.bb.controlled.fields=

# fields for course entities

group.bb.controlled.fields=TEMPLATE_COURSE_KEY,TEMPLATE_ORGANIZATION_KEY,X_BB_TEMPLATEKEY

# fields for Student entities

person.bb.controlled.fields=

# fields for enrollment entities

membership.bb.controlled.fields=

# fields for portal role membership entities

portalrolemembership.bb.controlled.fields=

# Copy configuration settings below

# Designates flag to enable announcement copying for configuration property file

announcements.copy=Y

# Designates flag to enable assessment copying for configuration property file

assessment.copy=Y

# Designates flag to enable calendar copying for configuration property file

calendar.copy=Y

# Designates flag to enable categories copying for configuration property file

categories.copy=Y

# Designates flag to enable chat archive copying for configuration property file

chat.archive.copy=Y

# Designates flag to enable chat session copying for configuration property file

chat.session.copy=Y

# Designates flag to enable course content copying for configuration property file

course.content.copy=Y

# Designates flag to enable course settings copying for configuration property file

course.settings.copy=Y


9.1 S

P6 BETA D

RAFT

Resources > Samples

# Designates flag to enable discussion board copying for configuration property file

discussion.board.copy=Y

# Designates flag to enable discussion board archive copying for configuration propertyfile

discussion.board.archive.copy=Y

# Designates flag to enable drop boxdata copying for configuration property file

drop.box.copy=Y

# Designates flag to enable glossary data copying for configuration property file

glossary.copy=Y

# Designates flag to enable gradebook data copying for configuration property file

gradebook.copy=Y

# Designates flag to enable course sub group copying for configuration property file

groups.copy=Y

# Designates flag to enable membership data without "private" data copying forconfiguration property file

membership.copy=Y

# Designates flag to enable "private" membership data copying for configuration propertyfile.

membership.exact.copy=Y

# Designates flag to enable Staff Information copying for configuration property file

staff.information.copy=Y

# Designates flag to enable tasks data copying for configuration property file

tasks.copy=Y

# used to denote data source to user for membership copy within cloning operation

membership.datasource.key=

# used to designate whether the course toc and tool settings are synched with the source

reconcile=Y

Sample XML Feed File

Sample of an XML User Feed File<ENTERPRISE>

<PROPERTIES lang="EN">

<DATASOURCE>Blackboard University</DATASOURCE>

<TARGET>Computing and Telecommunications LMS</TARGET>

<TYPE>Snapshot</TYPE>

<DATETIME>2009-12-21</DATETIME>

</PROPERTIES>

<PERSON>

<SOURCEDID>

<SOURCE>Blackboard University</SOURCE>


9.1 S

P6 BETA D

RAFT

Resources > Samples

<ID>39450210223



</ID>

</SOURCEDID>

<USERID>swang</USERID>

<NAME>

<FN>Mr. Stanley Wang Jr.</FN>

<SORT>Wang,Stanley</SORT>

<NICKNAME>Wang,Stanley</NICKNAME>

<N>

<FAMILY>Wang



</FAMILY>

<GIVEN>Stanley



</GIVEN>

<OTHER>Franklin



</OTHER>

<PREFIX>Mr.



</PREFIX>

<SUFFIX>Jr.</SUFFIX>

</N>

</NAME>

<DEMOGRAPHICS>

<GENDER>2</GENDER>

<BDAY>1982-01-01



</BDAY>

</DEMOGRAPHICS>


9.1 S

P6 BETA D

RAFT

Resources > Samples

<EMAIL>Swang5@Blackboard_university.com



</EMAIL>

<TEL teltype="1">3104591276



</TEL>

<TEL teltype="2">3104591200



</TEL>

<ADR>

<STREET>Twin Oaks Valley Rd



</STREET>

<STREET>attn: S. Wang



</STREET>

<LOCALITY>San Marcos



</LOCALITY>

<REGION>CA



</REGION>

<PCODE>92096-0001



</PCODE>

<COUNTRY>US



</COUNTRY>

</ADR>



9.1 S

P6 BETA D

RAFT

Resources > Samples

<EXTENSION>

<X_BB_SYSTEMROLE>0



</X_BB_SYSTEMROLE>

<X_BB_INSTITUTION_ROLE>0



</X_BB_INSTITUTION_ROLE>

<X_BB_STUDENTID>144532



</X_BB_STUDENTID>

<X_BB_PASSWORD>rpeterson



</X_BB_PASSWORD>

</EXTENSION>

</PERSON>

<PERSON>

<SOURCEDID>


<ID>12345678910



</ID>

</SOURCEDID>

<USERID>jINSTRUCTOR</USERID>

<NAME>

<FN>John Instructor</FN>

</NAME>

<DEMOGRAPHICS>

<GENDER>2</GENDER>

<BDAY>1970-03-01


9.1 S

P6 BETA D

RAFT

Resources > Samples



</BDAY>

</DEMOGRAPHICS>

<EMAIL>Swang5@Blackboard_university.com



</EMAIL>


</PERSON>

<GROUP transaction="1">

<SOURCEDID>

<SOURCE>UW-Superior</SOURCE>;

<ID>Summer2009_MATH_112_W06</ID>;

</SOURCEDID>

<DESCRIPTION>

<SHORT>Summer2009_MATH_112_W06</SHORT>

<LONG>Intro To Contemporary Math</LONG>

<FULL>The questions "What is mathematics used for?

What do mathematicians do? What do they practice or believein?" are raised and answered.Emphasis on developing the capacity to think logically and critically and to developstrong conceptual understanding and appreciation rather than computational expertise.Topics are selected from management science, statistics, social choice, and computerscience. Students see how mathematics is used to solve current problems.Satisfies theMathematics requirement for General Education.</FULL>

</DESCRIPTION>

<ORG>

<ORGNAME>Dept of Math & Comp Science</ORGNAME>

</ORG>

<TIMEFRAME>

<BEGIN restrict="0">2009-06-11</BEGIN>

<END restrict="0">2009-08-22</END>

<ADMINPERIOD>Summer2009</ADMINPERIOD>

</TIMEFRAME>

<ENROLLCONTROL>

<ENROLLACCEPT>1</ENROLLACCEPT>


9.1 S

P6 BETA D

RAFT

Resources > Samples

</ENROLLCONTROL>

<DATASOURCE>Extended Degree</DATASOURCE>

</GROUP>

<GROUP>

<SOURCEDID>


<ID>0390(2009-Fall)COMPSCI_697C_Sec._1-1164



</ID>

</SOURCEDID>

<DESCRIPTION>

<SHORT>Security_In_Computing



</SHORT>

<LONG>Graduate Level Special Topics Course covering security incomputing today.



</LONG>

<FULL>This Course will examine threats and security issues intoday's common computing environments. Prerequisites: Advanced Networks (CS 622) andCryptography (CS 633).



</FULL>

</DESCRIPTION>

<ORG>

<ORGNAM>Computer Science</ORGNAM>

</ORG>

<TIMEFRAME>

<BEGIN restrict="0">2009-09-01



</BEGIN>

<END restrict="0">2009-12-15


9.1 S

P6 BETA D

RAFT

Resources > Samples



</END>

<ADMINPERIOD>Fall 2009</ADMINPERIOD>

</TIMEFRAME>

<ENROLLCONTROL>

<ENROLLACCEPT>1</ENROLLACCEPT>

<URL>www.psunv.class.f2009</URL>

</ENROLLCONTROL>


<EXTENSION>

<BKBHIERARCHY>PSUNV LBART UGRD 0390 MATH10 1164</BKBHIERARCHY>

<GROUPTYPE>

<TYPEVALUE level="0">0</TYPEVALUE>



</GROUPTYPE>

<X_BB_TEMPLATEKEY>src101

</X_BB_TEMPLATEKEY>

</EXTENSION>

</GROUP>

<MEMBERSHIP>

<SOURCEDID>




</ID>

</SOURCEDID>

<MEMBER>

<SOURCEDID>


<ID>39450210223




9.1 S

P6 BETA D

RAFT

Resources > Samples

</ID>

</SOURCEDID>

<IDTYPE idtype="1"/>

<ROLE roletype="4">



<STATUS>1</STATUS>

<COMMENTS>Enrolled</COMMENTS>

<DATE>2009-09-01</DATE>

<TIMEFRAME>



</TIMEFRAME>

<FINALRESULT>

<MODE>Graded</MODE>

<RESULT>B</RESULT>

</FINALRESULT>

</ROLE>

<X_BB_ROW_STATUS>2</X_BB_ROW_STATUS>



</MEMBER>

<MEMBER>

<SOURCEDID>


<ID>12345678910



</ID>

</SOURCEDID>

<IDTYPE idtype="1"/>

<ROLE roletype="0">


9.1 S

P6 BETA D

RAFT

Resources > Samples



<TIMEFRAME>



</TIMEFRAME>

<SUBROLE>Primary Instructor</SUBROLE>

<STATUS>1</STATUS>

</ROLE>

<X_BB_ROW_STATUS>2</X_BB_ROW_STATUS>



</MEMBER>


</MEMBERSHIP>

</ENTERPRISE>

Secondary Institution RoleThe following is an example of the Secondary Institution Role. Secondary Institution Roles must be establishedusing an independent feed file after the Primary Institution Role has been added. Primary and SecondaryInstitution Roles cannot be stacked in the same XML file. The Secondary Institution Role should not be thesame as the Primary Institution Role. Only one SOURCEID tag and one ROLE tag can be inside each PORTAL_ROLE_MEMBERSHIP tag.

<ENTERPRISE>

<PORTAL_ROLE_MEMBERSHIP>

<SOURCEDID>


<ID>39450210223</ID>

</SOURCEDID>

<ROLE roletype="5"/>

</PORTAL_ROLE_MEMBERSHIP>


<SOURCEDID>


<ID>39450210223</ID>

</SOURCEDID>





9.1 S

P6 BETA D

RAFT

Resources > Samples

<SOURCEDID>


<ID>39450210334</ID>

</SOURCEDID>




<SOURCEDID>


<ID>39450210556</ID>

</SOURCEDID>



</ENTERPRISE>

Category and Category MembershipThe following is an example of the Category and CategoryMembership data types:

<ENTERPRISE>

<CATEGORY type="0">

<SOURCEDID>


<ID>crs_cat



</ID>

</SOURCEDID>

<EXTENSION>

<X_BB_TITLE>

Course Category

</X_BB_TITLE>

<X_BB_AVAILABLE >

Y

</X_BB_AVAILABLE >

</EXTENSION>

</CATEGORY>

<CATEGORY type="1">

<SOURCEDID>


<ID>org_cat



</ID>

</SOURCEDID>

<EXTENSION>

<X_BB_TITLE>

Organization Category


9.1 S

P6 BETA D

RAFT

Resources > Samples

</X_BB_TITLE>

<X_BB_AVAILABLE >

Y

</X_BB_AVAILABLE>

</EXTENSION>

</CATEGORY>

<CATEGORY_MEMBERSHIP type="0">

<SOURCEDID>




</ID>

</SOURCEDID>

<CATEGORY_MEMBER>

<SOURCEDID>


<ID>crs_cat



</ID>

</SOURCEDID>

</CATEGORY_MEMBER>

</CATEGORY_MEMBERSHIP>

<CATEGORY_MEMBERSHIP type="1">

<SOURCEDID>




</ID>

</SOURCEDID>

<CATEGORY_MEMBER>

<SOURCEDID>


<ID>org_cat



</ID>

</SOURCEDID>

</CATEGORY_MEMBER>

</CATEGORY_MEMBERSHIP>

</ENTERPRISE>


9.1 S

P6 BETA D

RAFT

blackboard learn 9.1 - server administration

Documents