Skip navigation
All Places > Blackboard Developer Community > Blackboard Learn Developers > Blog
1 2 Previous Next

Blackboard Learn Developers

20 posts


Posted by mkauffman Aug 4, 2017

This recently came up as a question from a partner, "In SaaS, can a external program call a JSP in the NOSESSION directory and thereby bypass Bb authentication?  This was possible in self and managed hosting of Learn."


I posted the question to our subject matter experts and got several responses that are quite helpful:

  1. You can just add authentication=“N” as an attribute to the <…Page> tag. Obviously, not recommended, nor ideal. Calling an endpoint remotely should have some sort of protection, even if it’s not via Learn. JSP seems like the worst way to accomplish this.
  2. Other than error pages, the only valid purpose I can see for requests NOT using a BbSession is a server/app/db liveness check, and we already have the /webapps/portal/healthCheck servlet for that purpose (which is a nosession servlet, and the only one we have in the app other than error pages). You really don't want to create a session for such requests that should merely check whether the server is up, but you also really shouldn't bombard the server with a multitude of such checks from different tools, or you're bound to introduce stability issues.
  3. There are other valid reasons I can think of.. The scorm AICC endpoint, the webservice endpoints etc all have their own authentication methods that don’t want a learn session. But I agree that they should be very careful about an unauthenticated endpoint.


Finally, when I mention JSPs being used as endpoints to our architects they all say that it far better to code using an MVC architecture where the endpoints are Java classes* (i.e. a method in a Spring controller) and JSPs are only used for the views. Both the JSP Model 1 and Model 2 architectures described here separate out logic from presentation.


*Not Java classes that are the result of the JSPs being compiled to Java.


Precompiling JSPs

Posted by scott.hurrey Jun 9, 2017

If you haven't read the Tomcat 8 section of the Preparing Your Building Blocks For Learn SaaS and Newer Learn Versions document, you should. As Blackboard continues to update to newer technologies, we are often looking at it as an opportunity to improve the product from a security, performance, and code quality perspective. This upgrade was certainly no different. As a matter of fact, the changes involved in Tomcat 8 to the way Building Blocks are handled is pretty substantial. While not a huge effort on your part is required to take advantage, some refactoring is required.


One of the biggest changes is that all Java Server Pages (JSPs) in your Building Block are expected to be precompiled. Its not a terribly difficult thing to do, but it does require an additional step in your build process. Historically -- and even currently if I'm honest -- Tomcat has handled the compilation on-demand; that is to say, the first time a user accesses a JSP, all of the JSPs are compiled. Not a huge deal, particularly if there are only a few to go through, but there is always the chance of a runtime compilation error and even if not, a busy system with a large number of compilations can be quite inconvenient to a student trying to get some work done.


So, as I set out to update the Building Blocks documentation, I realized I had never actually compiled a JSP myself. As you are probably aware, I am a Gradle user, and so I assumed someone out there must have tackled this problem before. I was right, sort of, but not nearly as many as I'd anticipated. Because of that, and because using the Blackboard Tag Libraries without having the tld and jar file in the WEB-INF directory introduced a complexity I could not find a solution to, I thought I would share what I did so you can think about how you might approach this.


Enter Benjamin Muschko.


Benjamin has done quite a bit of work around Gradle plugins, some of which I have used before, so I wasn't too surprised to see he had built the gradle-tomcat-plugin. There are others out there, but since I was familiar with the author, I decided to use this one. Setting it up and installing it is pretty trivial and pretty well documented in the README for the project. Essentially you must create a build script at the top of the build.gradle file to set up the classpath with a link to the plugin so you can apply it in your build file. Here is what that looks like:


buildscript {
    repositories {

    dependencies {
        classpath 'com.bmuschko:gradle-tomcat-plugin:2.2.5'

apply plugin: 'com.bmuschko.tomcat'
apply plugin: 'eclipse'
apply plugin: 'java'


Pretty straight forward, really. I should point out that I am using Gradle 3.3. If you are using an older version, upgrade. But if you don't want to, know that some of the syntax is different, and specifically, jcenter() is not a valid identifier, so you will need to manually reference as a maven repository, similar to how you declare the Blackboard maven repository. There are a millions google results to help you achieve that goal.


So I did this and the plugin was installed, and everything was great. The next step is to configure the plugin to use the appropriate version of Tomcat. This is extra important, because this plugin actually allows you to spin up a Tomcat server and run your code directly from Gradle. I'm not using it, but you definitely can. This also sets up your environment for compiling your JSPs.


Here is what that looks like according to the README :


// define the project's dependencies
dependencies {
   def tomcatVersion = '8.0.42'
    tomcat "org.apache.tomcat.embed:tomcat-embed-core:${tomcatVersion}",
    providedCompile "javax.servlet:servlet-api:2.5"

  // Dependencies are libraries needed to build, but should not be included in the B2 WAR.
  // You should NEVER include Learn JARs (other than webapis) in your B2.
  providedCompile( "blackboard.platform:bb-platform:$project.ext.learnVersion" ) { transitive = false }
  providedCompile( "blackboard.platform:bb-taglibs:$project.ext.learnVersion" ) { transitive = false }


So this was great. I did some optional configuration to turn of TLD verification and blam. Off to the races. Well, so I thought...


I ran the gradle command to compile the JSPs: gradle tomcatJasper, and after a few seconds, I received an error:

$ gradle tJ

:compileJava UP-TO-DATE
:tomcatJasper FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':tomcatJasper'.
> org.apache.jasper.JasperException: Unable to find taglib "bbNG" for URI: /bbNG


I did some noodling and playing and testing, and I figured that the problem must be that the classpath of the project wasn't being used as the classpath for the JSP compilation. I googled and yahooed and binged and I couldn't find any clear answer, so I did what I always do in this situation. I cried. Well, ok, I didn't, but I wanted to! Instead, I got a fresh cup of coffee and started reading the plugin code. In TomcatRun task, I came across a comment that said: "The web application's classpath. This classpath usually contains the external libraries assigned to the compile and runtime configurations."


I then looked at what the code was doing to set up the directory that the compilation was taking place, and it was essentially copying the WEB-INF folder. Because we use provideCompile to add the taglibs to the classpath but explicitly not include the jar file in the WEB-INF directory, there was no TLD to be found.


To test, I changed the dependency to compile and re-ran the test. I got a different message this time. AH HA!!


Of course, I can't leave the taglib in the Building Block, and I'm too lazy to change it back and forth to compile the JSP and then the WAR file, I had essentially confirmed the cause, but was still no closer to figuring out the solution. Again, I set my fingers in web crawl mode and hunkered down to search for ideas. After a couple of hours, my head hurt from banging it on the desk and my fingers were tired, and I still had no solution.


I took a step back and just looked through the build.gradle file to see what was there. I had tried adding additionalRuntimeResources, but that only works for TomcatRun and TomcatRunWar. I had tried creating my own classpath and adding the taglibs to the Gradle class path, and nothing. Then I noticed the tomcat dependency, and specifically how it was adding in a few libraries specifically to configure the plugin to setup the correct Tomcat version. I thought, what the heck, lets add the taglib there. I ran the task, and wouldn't you know it! I got the same error I got when I used compile instead of providedCompile. The error referenced the fact that it could not find one of the Blackboard objects, so i said, what the heck, let's add the platform jar, too, and low and behold, I got an error about the JSTL fmt tag library. I added that one, too, and I got those two words every Gradle user loves: BUILD SUCCESSFUL.


Here's what that looked like:


// define the project's dependencies
dependencies {
   def tomcatVersion = '8.0.42'
    tomcat "org.apache.tomcat.embed:tomcat-embed-core:${tomcatVersion}",

  providedCompile "javax.servlet:servlet-api:2.5"

  // Dependencies are libraries needed to build, but should not be included in the B2 WAR.
  // You should NEVER include Learn JARs (other than webapis) in your B2.
  provompile( "blackboard.platform:bb-platform:$project.ext.learnVersion" ) { transitive = false }
  providedCompile( "blackboard.platform:bb-taglibs:$project.ext.learnVersion" ) { transitive = false }


So after all of that, I finally had Gradle compiling my JSPs. Since I already survived the struggle, I thought I would share here with you!


I am very overdue in updating the basic-b2-template project, so I am doing that now, to include the precompilation and any other updates that are missing since Gradle 1.6 was cool. I will update the group when it is complete.


happy Developing!!


When Blackboard migrates a self or managed-hosted system to SaaS, the migration team and client sometimes choose to do a full database migration in order to maintain existing content. Your B2's database tables will be migrated by this process, but if your B2 code relies on any database sequences, you'll need to work with the migration team to ensure that the sequences are correctly set up on the new SaaS system as well.


Bye Bye BBLEARN & bb_bb60

Posted by mkauffman May 14, 2017

Please read carefully. Your integration will break in SaaS if you have issues caused by hard-coded use of BBLEARN and bb_bb60. Though the title is a bit-overdramatic and BBLEARN and bb_bb60 will still be around on self-hosted and managed-hosted systems, they are gone in SaaS.


BBLEARN are bb_bb60 are the schema names used on many self and managed-hosted systems. These are no longer used on SaaS systems. Instead a long string like BB589bd9cca452e is used as the schema name. Every SaaS system will have a different schema name for its database. This means that no external system can make assumptions about the schema name and no B2 code can count on some particular set of values. All code must dynamically determine the schema name, or at the very least it must be set up during configuration. The Learn Java API blackboard.platfomr.plugin.PlugInUtil.getUriStem method can be used to get the complete B2 web application name, including the schema name. For example, on, String uriStem = PlugInUtil.getUriStem("bbdn", "bblogbackb2"); currently returns the string: /webapps/bbdn-bblogbackb2-BB56d7008520956/ See GitHub - mark-b-kauffman/bbdn-bblogbackb2: Demo the use of Logback to create log files.   for example use code.


Should your B2 be exposing Web Service endpoints and your external server assumes the endpoint is either BBLEARN or bb_bb60, the fact that SaaS now uses a different schema name on every SaaS system will cause problems for your integration. You external server must now be given either programmatically, or during configuration, the actual schema name so that it can make calls to valid URIs for each Learn system.  The more dynamic you make your code, the better.


The other case that will cause issues is if your B2 code refers to itself on the Learn system using URIs that it assumes contain either bb_bb60 or BBLEARN. The code must no longer make that assumption. Instead use PlugInUtil.getUriStem() to determine the actual value.


A brief video explanation - 2017-05-18_1526

Please read ALL FILES No More

For self-hosted Unix installations see How much longer will Red Hat 5 be supported?


Blackboard Learn Mobile

Posted by mkauffman Mar 7, 2017

We've had several developers ask about registering Mobile Web Services. The first step is to read this article on how to Configure and Register Blackboard Mobile Web Services. After reading, the common roadblock is filling out the registration form, hitting submit, and then the page reloads with the default values, like nothing happened. What's wrong? The answer is that the server must be on the public internet and have a valid SSL certificate installed. This has to be because the Mobile service is a cloud service that talks back to your Learn instance.

This just in. bb-manifest.xml files will not upload to SaaS when the XML does not meet the standard: Extensible Markup Language (XML) 1.0 (Second Edition) .As we don't check this in Self and Managed-hosted systems, you may have had URLs in your bb-manifest.xml file using the following format:

<url value="itemanalysis/showItemAnalysis?action=display&;course_id=@X@course.pk_string@X@" />


These should be written as follows because the & character in XML must be encoded:

<url value="itemanalysis/showItemAnalysis?action=display&amp;course_id=@X@course.pk_string@X@" />

I’m writing this to let you know that we’ve run into a new issue with the SAML B2 on a few Learn systems that then causes problems for other B2s that make outbound connections from Learn. We're still working to determine the Learn & SAML B2 versions affected. To date we've seen this on a Q2 2016 system with the 3000.1.0 version of SAML, and a SaaS 3100.9 system running version 3100.9 of SAML.


If the lines shown below are found in the stdout-stderr logs, please open a ticket using your Behind the Blackboard account, include the logs, the Learn version, and the version of the SAML authorization B2. Reference LRN-121348 early in the case description so that support is aware that this is a known issue. While you're on Behind the Blackboard, be sure to subscribe to the Learn support bulletins (Top menu, My Account, MY SUBSCRIPTiONS).


Here are the lines your will see in the stdout-stderr files on an affected system; nested exception is org.springframework.beans.factory.BeanCreationException: Error creating bean with name 'keyManager' defined in ServletContext resource [/WEB-INF/config/saml/securityContext.xml]: Invocation of init method failed; nested exception is java.lang.RuntimeException: Unable to load aliases from keyStore


There may be other exceptions that the SAML B2 throws that will cause the issue. The above is one example. The main point is that for this issue to occur the SAML B2 must throw an exception and stop running.


... then later in the log file ...

INFO   | jvm 2    | < information about your B2 wil be here>  threw exception [Handler dispatch failed; nested exception is java.lang.NoClassDefFoundError: org/apache/commons/httpclient/params/HttpConnectionParams] with root cause

INFO   | jvm 2    | 2017/02/15 18:55:54 | java.lang.NoClassDefFoundError: org/apache/commons/httpclient/params/HttpConnectionParams

INFO   | jvm 2    | 2017/02/15 18:55:54 |     at

INFO   | jvm 2    | 2017/02/15 18:55:54 |     at


The main point of the above is that we can see that your B2 threw an error because the system was incorrectly handing it the SAML socket factory.

This came up in a recent case with a Partner. Their B2 is exposing a new endpoint in Learn for their external server make calls to. (Example: webapps/abc-myb2-VeryLogSaaSDBschemaName/MyEndpoint) Everything worked fine on their test system. But when they deployed to a recent 3100 build, the calls the external server made were not getting through to Learn. Why? Because newer builds of Learn have the 'Security Management: Cookie Disclosure' B2 installed and active. This B2 forces you to accept Blackboard's Cookie Disclosure Agreement before logging in. It also blocks incoming calls to endpoints like that described. There is no impact on our REST APIs. I've not checked our Web Service SOAP APIs yet... In any case, how do you work around it? Put a cookie in your cookie jar. Just set a cookie with name="COOKIE_CONSENT_ACCEPTED" and path="/" in your cookie jar, so it's sent with every request. Hope this helps the next developer who runs into this one!

The upcoming release of Blackboard Learn 9.1 Q2 2016 will be upgraded to run on the latest version of Java from Oracle, Java 8.  The primary impact of this change will be to Building Blocks.  Nearly all Building Blocks are expected to continue to work without any changes as, generally, most Java 7 code is compatible with Java 8 code.  There may be instances, however, where a Building Block will need to be updated.  You may need to update a Building Block if:

  • During compilation, the values for compatibility, source, and target were not specified in a way compatible with Java 8.
  • A Building Block uses complex Java 7 libraries.
  • A Building Block that relies on the Spring Framework must be updated to use Spring 4.2.0+.


The following resources are available to assist you in the evaluation and updating of your Building Blocks for Java 8:


We strongly encourage anyone who has a Building Block to test it against Java 8 before installing the Learn 9.1 Q2 2016 release onto a production environment. 


Preparing Building Blocks for Release 3000.1.0 in SaaS and the Java 8 Update


The information above is also applicable to SaaS Plus/Advantage deployments where clients can add their own Building Blocks. In addition to the above resources, developers should be aware of additional possible updates that may be required in these deployments:

Greetings Developer Community,


It’s been a few months since the Developer Community moved to We hope you’re enjoying the collaborative features that this site offers. Between discussions, blogs, ideas, and questions, there are a lot of content types to help you learn from other developers and post your own successes for fellow community members.


Now that we’re properly established on the Community site, we are entering the next phase of migration from moving all developer documentation to this site. Soon you will be able to find all Blackboard Learn developer resources here. This is exciting news, but we also want to give you advance warning: we’re retiring on Dec 31, 2015, after the migration is complete.


We’ll have a few redirects in place from the most common links that people visit, so those links will take you directly to the corresponding section on this site. Jive will continue to serve the community well when it comes to finding, using, and discussing developer information. For a long time, the EduGarage forums were the most active part of the site and we hope that trend continues here. We are still identifying if and how to archive the data in the edugarage forums in how to make them searchable if we do, but all further communication will take place here in the discussions section. We will redirect to the new site, as well.


As we move the content in the next few weeks, we’re also updating it for accuracy and usefulness. Please bear with us while some of the content is under construction or if some information is initially moved and then removed (i.e. Powerlinks documentation). We will be tagging everything that is migrated as 'migrated from edugarage' so you know where it came from. If you notice a broken hyperlink or something looks a bit off, let an admin know by leaving a comment or sending a message and we’ll take care of it as soon as possible.


If you have any questions, please let us know! We don’t want this to be a surprise, so we’re putting a banner on EduGarage to announce the migration there as well. Please share the news with your networks as appropriate.


Thank you for your patience and understanding. I look forward to continuing to build the Developer Community in collaboration with all of you here in Jive!

This is my cheatsheet for the Bb DEV Virtual Machine (managed by Vagrant).


Vagrant command line

Where to run the commands on Windows: Run > cmd > C:\Users\[my user]\[the_folder_with_the_april_release_box + vagrant_file]> <run your command here>

-> vagrant up

-> vagrant halt

-> vagrant reload (after applying changes to the Vagrantfile)

-> vagrant box list
-> vagrant plugin install vagrant-hostupdater
-> vagrant ssh

-> vagrant destroy

-> vagrant box remove


SSH connection to the back-end

Note that on a Windows host machine you may experience issues, hence for the SSH connection use instead putty or MobaXterm or RemoteNG:

-> Host:

-> Username: vagrant
->  Port: 2222 (do not use 22) (Blackboard box OR e.g: lucid32 Ubuntu box)

Port: 2200 (in case you assigned the 2222 to other box, use the port 2200 for the Blackboard box)

-> vagrant@'s password: vagrant


SSL certs

SSL cert (it has a Private key, but it is not a CA cert): C:/Users/[my user]/.vagrant.d/insecure_private_key


Manage the Learn Bb VM: edit bb-config, use the command line admin tools

-> sudo /usr/local/blackboard/tools/admin/ services.start

-> sudo vi /usr/local/blackboard/config/ (save & exit: ESC ZZ)

-> sudo /usr/local/blackboard/tools/admin/ services.start


GUI access to the Learn Bb VM

-> April 2014 and above: https://localhost:9877/ (web browser) u: administrator - p: password


Example of a "Vagrantfile"


Vagrant.configure("2") do |config|


  config.vm.provider :virtualbox do |vb|
    vb.customize ["modifyvm", :id, "--memory", "4096"]
  end = 'bb-learn-9.1.201404.160205'
  config.vm.box_url = './' :forwarded_port, guest: 8080, host: 9876 :forwarded_port, guest: 8443, host: 9877 :forwarded_port, guest: 2222, host: 9878


There are a few template variables you can use to render platform, user or course information dynamically in contents, LTI custom params and other places. This is quite powerful, but it can be better...


With a custom template variable Building Block you can define new template variables to render virtually anything in your contents, from your Blackboard Learn instance using the API or taking data from the data base, or from an external system using web services, external data bases, etc... You can even render not only strings, but even html snippets to add dynamically, for instance, search forms from your Library service.


This is made by creating an extension Building Block, for what you have to include :


 <webapp-type value="javaext" />


in your bb-manifest.xml file.


You also have to declare in the same file your custom context handler, defining your extension with:


   <definition namespace="blackboard.platform">
    <extension id="customContextHandler"
      singleton="false" />


Then, in your source code, you create your custom context handler:



import java.util.ArrayList;
import java.util.LinkedList;
import java.util.List;

import javax.servlet.http.HttpServletRequest;

import blackboard.persist.BbPersistenceManager;
import blackboard.platform.context.Context;
import blackboard.platform.context.ContextEntry;
import blackboard.platform.context.ContextHandler;
import blackboard.util.resolver.Resolver;

//Extends ContextHandler class to include our variable resolver
public class CustomContextHandler implements ContextHandler {

  public CustomContextHandler() {

  public Entitlements getEffectiveEntitlements(Context ctx) {
       return new EntitlementList();

  public Entitlements getRestrictedEntitlements(Context ctx) {
       return null;

  public List<SecurityContext> getSecurityContexts(Context unused) {
       return new ArrayList<SecurityContext>();

  // Here is were we inyect our custom resolver
  public List<ContextEntry> resolveKeys(HttpServletRequest request,
  BbPersistenceManager unused) {
       CustomResolver resolver = new CustomResolver(request);
       return new LinkedList<ContextEntry>();



And now implement the custom resolver who contains the logic to show what you want where you insert your template variable:



import javax.servlet.http.HttpServletRequest;

import blackboard.platform.context.ContextManagerFactory;
import blackboard.util.resolver.ResolverComponent;

public class CustomResolver implements ResolverComponent {

  private static HttpServletRequest _request = null;

  public CustomResolver(HttpServletRequest request) {
       _request = request;

  public String[] getKeys() {

       return (new String[] { "variable_key" }); // the first part of the
                                                    // template variable (@X@
                                                    // tag) - variable_key in

  public String resolve(String method, String attributes[]) {
       String varout = null;

       if ("show".equalsIgnoreCase(method)) { // the second part of the @X@
                                                 // tag - show in
       try {

          String uriPrefix = Utils.getUriPrefix();
          // the code for inserting
          // the Unika search box
          varout = "Whatever you whant to show in your template variable <div></div><script></script>...";
          return varout;

       } catch (Exception e) {

       } finally {



       return null;




Now typing in your contents you will get the rendered html code you put in varout.


This technique has been very useful to me in different projects, so I hope this helps to somebody else.