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.

Comments (Comment Moderation is enabled. Your comment will not appear until approved.)
Hi Bruce,

First of all I must thank you for your effort in compiling this blog on using Bb Learn 9 web services. This is immensely helpful since BB hasn’t published anything on how to use their web services.

I have configured your “Register Proxy Tool” application and I am trying to register a proxy tool (by running the java client) with a BB Learn application instance running on a managed hosting environment.
However, I am unable to complete the registration, and am getting the following error : “edu.ku.it.si.registerproxytool.controller.RegisterToolController.registerProxyToolWithBlackboard:82 - There was an error in registering the tool: Connection timed out: connect”.

Have you got any suggestions why it might be timing out all the time? I am in a network which is using a proxy to connect to the internet and I wonder whether that is the case?
Any help in this matter is highly appreciated. Thanks,

Luckshan.
# Posted By Luckshan Tantirige | 8/31/10 2:28 AM
Luckshan:

First step is to double check the values for the properties in
bbws.properties file. Make sure those values are for the Blackboard installation that you want to register the proxy tool with.

Make sure you have correctly set the values in your Blackboard learn 9 Proxy Tool Global Properties (see above).

If all of that is correct, try to use the program from a network that is not using a proxy to connect to the internet.

If you cannot successfully register your proxy tool after doing the above then I'd post the question in the blackboard developer's forum on edugarage.

Bruce
# Posted By Bruce | 8/31/10 5:06 PM
Bruce,

Thanks you very much for your response. It was actually the network proxy that was blocking the web service call. The program worked without issues when I tested with a different internet connection.

Regards,
Luckshan.
# Posted By Luckshan | 9/2/10 2:57 AM
Call me daft, but I can't seem to find a rampart.mar file? In either the src or bin downloads???

Could you please explain where you are getting the .mar file from?
# Posted By Anonee Mouse | 9/16/10 5:12 AM
Anonee:

Go here: http://ws.apache.org/rampart/download.html.
Click on version 1.5
Click on the zip link for the standard binary distribution
After the download completes unzip the rampart-dist-1.5-bin.zip
In the rampart-1.5 folder created when you unzip the above is a modules folder. In that folder is rampart-1.5.mar

Bruce
# Posted By Bruce | 9/16/10 8:58 AM
Hi Bruce,

I have started using Blackboard web service to integrate some of our internal systems with BB data entities.

I am using the “Courses.WS” web service at the moment, to retrieve a number of courses from Blackboard, by providing a number of Course IDs.

I am having an issue, that is, the client (using Axis2) times out when I give a certain number of Course IDs as input. For example it works fine with about 1300 client IDs passed, but fails when I pass 1500 client IDs.

Given below is part of the error that I get:

org.apache.axis2.AxisFault: Read timed out
   at org.apache.axis2.AxisFault.makeFault(AxisFault.java:430)
   at org.apache.axis2.transport.http.HTTPSender.sendViaPost(HTTPSender.java:203)
   at org.apache.axis2.transport.http.HTTPSender.send(HTTPSender.java:76)
   at org.apache.axis2.transport.http.CommonsHTTPTransportSender.writeMessageWithCommons(CommonsHTTPTransportSender.java:400)
   at org.apache.axis2.transport.http.CommonsHTTPTransportSender.invoke(CommonsHTTPTransportSender.java:225)
   at org.apache.axis2.engine.AxisEngine.send(AxisEngine.java:435)
   at org.apache.axis2.description.OutInAxisOperationClient.send(OutInAxisOperation.java:402)
   at org.apache.axis2.description.OutInAxisOperationClient.executeImpl(OutInAxisOperation.java:229)
   at org.apache.axis2.client.OperationClient.execute(OperationClient.java:165)

I have tried increasing the client timeout using options.setTimeOutInMilliSeconds(xxx), but haven’t had any luck.

Would you be able to shed some light into what else I can try to resolve this?

Thanks,
Luckshan.
# Posted By Luckshan Tantirige | 9/24/10 12:42 AM
Luckshan - I've not sent that many course ids to the web service so I've not had a timeout problem. Try posting your issue on Blackboard edugarage forum (http://forums.edugarage.com/forums/) and you could also try emailing Scott Hurrey, who is a Blackboard person responsible for developer relations. His email is:
scott.hurrey@blackboard.com.

Bruce
# Posted By Bruce | 9/24/10 3:03 PM
I appreciate this site, but I have the same question above. I don't see a rampart-1.5.mar file. I file called rampart-1.5 whose type is a "Microsoft Office Access Report Shortcut". When I use this file, I get this failure when I run the registration:

2010-12-09 17:46:04,573 ERROR edu.ku.it.si.registerproxytool.controller.RegisterToolController.registerProxyToolWithBlackboard:82 - There was an error in registering the tool: Unable to engage module : rampart
# Posted By Frank | 12/9/10 6:53 PM
Frank:

I think your problem may be related to your Windows operating system because the file name has a period in it. Try renaming the file to rampart.mar in the modules directory.
# Posted By Bruce | 12/10/10 10:17 AM
Bruce,

Thanks for the reply, but that doesn't seem to be it. I've tried just about every combination I can think of. rampart.mar, rampart, rampart_1.5, rampart_1.5.mar...nothing works.

Again, this file I got from rampart looks funny to me because it's not really a file per se, it's a shortcut. Is that what a .mar file is? I've never worked with one.
# Posted By Frank | 12/10/10 2:53 PM
I am using registerproxytool
I am getting exception
Exception :: org.apache.axis2.AxisFault: Transport error: 404 Error: Not Found
Same issue found when I tried to access WS using SOAP UI.

In soap ui request xml is :-
<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">...;;
<soap:Header>
   <wsse:Security>
<wsse:UsernameToken>
      <wsse:userName>session</wsse:userName>
<wsse:password>nosession</wsse:password>
</wsse:UsernameToken>
</wsse:Security>
</soap:Header>
<soapenv:Body/>
</soapenv:Envelope>


Response -
IIS 7.5 Detailed Error - 404.0 - Not Found
# Posted By Girish | 1/18/11 2:12 AM
Frank - please try changing the rampart.mar to rampart.jar

Mark Kaufman posted this on EduGarage:
These tutorials are great. Thank you! I'm working at CSU Chico. We're moving from Vista 8.0 to Blackboard Learn 9.1. I'd created a web application that our staff and instructors use with Vista that allows them to do some things for themselves - that I'm now porting to work with Blackboard Learn 9.1. This code is a tremendous boon. One thing I did discover is that I had to change the .mar files to .jar files because I'm working on a Windows 7 system with Office - the OS forces .mar to be interpreted as Micorsoft Access Archive shortcut so the Java code reports rampart as missing when it runs. Changing .mar to .jar resolves that. The other piece that bit me is that I misinterpreted bbws.blackboardServerURL= in the .properties as wanting a URL. I should have read the comment - a FQDN, like myBBserver.myco.com works.
# Posted By Bruce | 1/21/11 11:53 AM
Just a note to say thank you for posting these instructions. While I don't use Java (I use python) the screen shots and steps alone have been a great help.

In case anybody else comes across these notes and wishes to use the webservices with python they might find this code from Chris Greenough useful too:

http://code.google.com/p/bbpy/
# Posted By Sion Morris | 1/12/12 10:18 AM
When I open the project in eclipse, many of the packages have missing dependencies. For instance, Import org.springframework.context.ApplicationContext; cannot be resolved. I understand it is looking for the jar file for these, but are they not included in the example, or in maven? What am I not getting? I'm pretty new to this.
# Posted By Dave | 2/28/12 4:00 PM
Dave - make sure you have the m2eclipse plugin installed in your Eclipse IDE. The project uses Maven to resolve dependencies.

If you're not familiar with Maven visit: http://www.sonatype.com/books/mvnref-book/referenc...
# Posted By Bruce | 2/28/12 4:10 PM
I managed to get the dependencies problem corrected. Just needed to convert my eclipse project to a maven project and then have it import the dependencies. But now I am stuck on the "Unable to engage module : rampart" error. I changed the file from .mar to .jar and it is still not working. I have the modules folder on my desktop and my properties file is listing the path as: bbws.modulePath=/Documents and Settings/dave/Desktop/modules. I've tried adding in the file after modules and even leaving off the modules folder, but still get the same error. Thanks again for helping a complete newb try to work his way through this.
# Posted By Dave | 2/29/12 2:52 PM
try changing the location rampart.mar to a folder directly off your root (e.g. c:/rampart) and ensure that complete path to that folder has no spaces.

be sure to update the properties file with the new path
# Posted By Bruce | 2/29/12 3:26 PM
Still having no luck. I put the modules folder containing the rampart.jar file on the root directory and then changed the path to bbws.modulePath=C:\\modules and I still get the same error. I know it must be finding the path, because if I change the name of the modules folder it then tells me the location couldn't be found. Could it be that the change from .mar to .jar didn't work? When I changed it to .jar the file shows up as a java file and no longer a link to the Microsoft access archive. However, the only way I could get it to change was to change the name while it was still a part of the archive file. Otherwise (even though I have set windows to display file extensions) the extension for the .mar file will not display.
# Posted By Dave | 3/1/12 1:16 PM
Hey, after more digging (http://forums.edugarage.com/forums/p/2751/8178.asp...) I edited the path to the modules to be C:\\ from C:\\modules -- just omit the modules sub-dir
# Posted By Baci | 5/15/12 9:56 AM
Hi there. Our Blackboard Learn 9.1 SP9 runs on a closed network and we are having some issues running WSSE. Can this approach bypass the WSSE (and the security header) when using WSDL?

Thanks!
# Posted By Greg | 5/9/13 6:51 AM
@Greg - I don't know of a way to bypass the security header.
# Posted By Bruce | 5/9/13 7:05 AM
@Bruce - So we pass the same WSSE parameters (like Oasis.com) through proxy?
# Posted By Greg | 5/9/13 7:11 AM
Hi
Just registered a proxy tool using this example. Thank you. One thing that caught me out is that it assumes http and not https

I edited:
RegisterToolServiceImpl
to point use https, otherwise I get 302 redirect exceptions which it doesn't follow.
ContextWSStub contextWSStub = new ContextWSStub(context, "https://";
            + blackboardServerURL + "/webapps/ws/services/Context.WS");

Just might be useful for someone else on https

Thanks
Jason
# Posted By Jason Bailey | 7/25/14 10:56 AM
I have initialize the bbws properties. When I try to run RegisterProxyToolApp.java, It return an error : 2016-01-06 14:45:49,992 ERROR edu.ku.it.si.registerproxytool.controller.RegisterToolController.registerProxyToolWithBlackboard:84 - There was an error in registering the tool: Connection refused: connect
I'm waiting for your helps
Tks
# Posted By Aymen | 1/6/16 9:02 AM
BlogCFC was created by Raymond Camden. This blog is running version 5.9.1.002. Contact Blog Owner