Using Blackboard Learn 9 Web Services - Part 1 Logging In Using A Proxy Tool

Introduction

With release 9 of the Blackboard Learn system, developers have a new way to get data out of Blackboard for use in external applications. Blackboard now provides extensive SOAP web services that can be called from applications running outside the Blackboard platform. These SOAP web services can be used to both get data out of Blackboard and to update/add data in Blackboard.

Currently (August 2010) there is limited documentation on how to use these new web services. Since the university I work for is transitioning to Blackboard Learn 9.1, I will be writing a series of articles on how Java developers can use these new web services.

To follow along with these tutorials you'll need access to Blackboard Learn 9.1 or higher, including the ability to login (or have someone who can login) as a system administrator.

To use the Blackboard Learn 9.1 web services you must first have your client application login to the Blackboard system using the Context web service. There are two main login methods. One is to login using a username and password of a Blackboard user who has enough rights to execute the web service classes and methods you need to use (for example a system administrator or for limited web services you could use a student login). The second method is to login using a proxy tool that was previously registered and authorized.

A proxy tool is a client program identified by a specific name and that has a shared secret that must be passed in when logging in. A proxy tool first must be registered with your Blackboard installation. After the proxy tool is registered, a Blackboard system administrator must authorize the client program so that it can be used to login and make calls to the Blackboard web services. The proxy tool will only be allowed to access those web service classes and methods it requested access to and that were authorized by the Blackboard system administrator.

Setup The Proxy Tool

Login to Blackboard as an administrator. Click on the System Admin tab, then click on the Building Blocks, then click on Proxy Tools, then click on Manage Global Properties. You should see:

Note the value for Proxy Tool Registration Password. You'll need to use that value when registering your proxy tool.

Make The Blackboard Learn 9.1 Web Services Available

We next must make the Blackboard Learn 9.1 web services available. Click on the System Admin tab, then click on the Web Services link (under Building Blocks). You should see:

Click on the check box next to Web Service Name to select all the web services. Then click on the down arrow next to Availability and select Make Available. Repeat this step for SSL (set as not required) and Discoverability (make discoverable). To change the Logging value from the default of Common to Individual click on the check box for the web service. Then click on the down arrow next to that Web Service name and select Edit. You should see:

In the Edit screen change Select Logging Type from Common to Individual. Make a note of the Log File Location (e.g. /u02/blackboard/logs/ws/Context.WS.log) in case you need to review the log when a problem occurs. Click on the submit button to save your changes.

Note you can make only certain web services available by checking just the box next to a specific web service and then clicking on the down arrow next to Availability. Also, in a production system you should carefully consider which web services you will make available and whether or not those web services should require https.

Setup Rampart Module

To enable security for our requests to the Blackboard web services we will use Apache Rampart. Any call to a Blackboard Learn 9.1 web service requires a SOAP envelope that has a security header. Rampart will help us create the security header.

Download from http://ws.apache.org/rampart/download.html the Apache Rampart Module. Unzip the download. Copy rampart-1.5.mar (or whatever version of rampart.mar you downloaded) to a folder named modules on your computer. Be sure to note the path to the modules folder as you'll need that path later when setting up the registerproxytool program (see below).

Setup And Run The registerproxytool program

Download the registerproxytool program from /blackboard/registerproxytool.zip.

The download is an archived Eclipse project created using Eclipse 3.5 and Maven 2. The program demonstrates how to register a proxy tool with a Blackboard installation using the Blackboard Learn 9.1 Context web service.

To import the project into your Eclipse workspace you'll need to be using Eclipse 3.5 or higher with the Maven 2 plugin. You can get Eclipse at http://www.eclipse.org/. Information about installing the Eclipse Maven 2 plugin is at http://m2eclipse.sonatype.org/installing-m2eclipse.html.

After importing the archived project into your Eclipse workspace read the ReadMe.txt file to view how to configure the application and how to run it. Before running the program you'll need to set the values for the properties listed in the bbws.properties file. Those values are for the Blackboard installation that you want to register the proxy tool with.

Note the registerproxytool program uses two class in package edu.ku.it.si.bbcontextws.generated. To register a proxy tool you use the Blackboard Learn 9.1 Context web service so I previously generated the client classes for that web service and copied them into this project. These classes were generated using Axis2 and the WSDL file for the Blackboard Learn 9.1 Context web service. I'll cover in a future tutorial how to generate the Blackboard web service client files using Axis 2 and the Blackboard Learn 9.1 web service WSDL files.

Troubleshooting Problems Registering A Proxy Tool

You can only register a proxy tool once. If you need to re-register the same proxy tool, you must first delete the proxy tool using System Admin – Building Blocks – Proxy Tools (click on the down arrow next to the Proxy Tool name and select Delete).

If the registerproxytool program was not able to register your proxy tool, there should be one or more error messages in the Console window. You can also view the log file for the context web service (the context web service is used to register the proxy tool) in your Blackboard installation.

Authorize The Proxy Tool

After successfully running the registerproxytool program to register your proxy tool with Blackboard Learn 9.1 web services you will need to login in to Blackboard as a System Administrator and change the availability of the proxy tool from No to Yes.

After logging in go to System Admin – Building Blocks – Proxy Tools. Click on the down arrow next to the proxy tool name and select Edit. You should see:

Click on the Yes radio button for Availability and then click on the Submit button to make the change. The Availability column should now have a value of Yes for that proxy tool.

Login In To Blackboard Web Services Using The Proxy Tool

To test that you can login to the Blackboard Learn 9.1 web services using the proxy tool you registered above you can run the LoginApp that is part of the registerproxytool program.

In Eclipse right click on /src/main/java/edu/ku/it/si/login/app/LoginApp and select Run As – Java Application. The result of trying to login will be displayed in the Console window.

Summary

Blackboard Learn 9 provides extensive SOAP web services that external applications can use to get data out of Blackboard and to update/add data in Blackboard. The first step in using these web services is to make the services available and then to setup a proxy tool that can be used to login and that is authorized to access the web service classes and methods your external application needs to use.

In the next tutorial I'll cover how to determine which Blackboard web service classes you need to use to get specific data out of or to update/add data into Blackboard.