Blackboard Learn 9.1 Web Services Tutorials and Documentation

Blackboard Learn provides extensive web services that external applications may use to get information from and add information to Blackboard. The below links can be used to learn about Blackboard Learn 9.1 web services and to download Java applications that demonstrate how to use the web services.

I wrote these Java example applications, tutorials and documentation based on updated versions of my previous blog articles on Blackboard Learn's web services. Each file includes a link to download an example Java application that can be viewed in any Maven compatible Java IDE. The example applications include a detailed ReadMe.txt file that explains how to build and run the example either in Eclipse or just using Maven.

These documents will become the references I will use in preparing my presentation on Blackboard's web services, which I'll give in July 2011 at the Blackboard Developer's conference.

Please use the Add Comment link below to provide any feedback. I'm especially interested in any feedback from Java developers who were not able to run the example applications with their own Blackboard installation.


  1. Blackboard Web Services Presentation
  2. Part 1 - Setup A Proxy Tool For Accessing Blackboard's Web Services
  3. Part 2 - How To Learn About Specific Blackboard Learn 9.1 Web Service Classes
  4. Part 3 - How To Generate Java Client Classes For Blackboard Learn 9.1 Web Services
  5. Part 4 - How To Use Blackboard Learn 9.1 User Web Service (Updated - Updating an existing Blackboard user now works)
  6. Part 5 - View The SOAP Request and Response

Comments (Comment Moderation is enabled. Your comment will not appear until approved.)
Bruce, Thanks for your great documentation! We're using CF9 to try and pull Blackboard WS into a Liferay portal via a CF portlet (cfc). We're also authenticated using CAS. We finally got CF to deploy and not dump it's configurations whenever we updated cfcs. Now we'd like to access BbWS. What do you think will be the best method given our CAS'ified authentication. User or Proxy?
# Posted By Baci | 2/20/12 3:41 PM
Baci - I'd still recommend using proxy. I think its the best approach that allows you to tailor the access for applications using that proxy.

Since your CFC functions will be interacting with the BB web service you should not have any issues with CAS.

If you get CF to interact with the BB web services please be sure to post that. There are several example applications that use Java or C# with BB web services, but nothing I know of that uses CF.

Also depending on what you need to do - it may be simpler to query directly the BB database. Blackboard does support select database queries and now publishes their database schema. If you just need to get information out of Blackboard, we've found querying the Blackboard database much simpler to implement.
# Posted By Bruce | 2/20/12 5:09 PM
Finally getting around to this. Thanks for the excellent documentation. We're in a managed hosting environment. I'm unclear about where the rampart.mar file needs to live. Im building the registerproxytool locally (not on the machine hosting our Bb 9.1 sp8 install. Does the rampart.mar need to be on the Bb server or can I path to it local to my eclipse application? Thanks for any assistance.
# Posted By Baci | 5/10/12 3:46 PM
Baci - The rampart.mar goes on the same server where the RegisterProxyTool will run. If that's is your local computer then that is where rampart.mar goes.
# Posted By Bruce | 5/10/12 4:19 PM
Bruce, just a quick note to let you know we actually got this working. CF is now getting a proper response from our BbWS via loginTool. Now we can tear into the WS API. The most difficult part was to form the request xml (timestamp proved to be the most difficult). I hope to post the resolution, not sure where yet.
# Posted By Baci | 5/22/12 10:35 AM
The CF code to interact with the BB web service, was that ever posted? Just wondering, due to having to begin a similar project here and CF seems to be the code of choice for the development.
# Posted By Matt | 7/24/13 8:35 AM
This code is a big help. However, I am having a lot of trouble getting the web client to connect to the server. I have the BBLearn server running in a VM on my desktop machine and I have the example web client running on the same machine. I setup a host only network and I can connect with the browser to the URL but I cannot get the web service to communicate to this URL (set it in file).
# Posted By Jef | 7/25/14 1:36 PM
I tried running the RegisterProxyToolApp with NetBeans 8, but got the following error message, did I miss anything?

Final Memory: 7M/162M
Failed to execute goal org.codehaus.mojo:exec-maven-plugin:1.2.1:exec (default-cli) on project registerproxytool: Command execution failed. Process exited with an error: 1 (Exit value: 1) -> [Help 1]

To see the full stack trace of the errors, re-run Maven with the -e switch.
Re-run Maven using the -X switch to enable full debug logging.

For more information about the errors and possible solutions, please read the following articles:
[Help 1]
# Posted By Tom | 10/5/14 8:36 PM
Hi Bruce, first of all thanks for this great information, it is great to keep learning from you after bbworld.

I'm trying to install a proxy tool so I can use webservices from blackboard. After following every step as described in the document "How To Login Using A Proxy Tool" I'm having this error when Running As Java Application.

ERROR - There was an error in registering the tool: [WSFW009]Rejecting webservice call: Service Context.WS is not active (operation: initialize)

It's weird because I already have available all of the webservices in my blackboard settings.

Would you please give me some advice?

Best regards!
# Posted By Juan | 10/9/14 11:20 AM
Hi Bruce,

Your documentation has been very helpful. I know in your latest update for saving/deleting a user, I was able to get that to work as well. What I'm trying to do now is to get a grade and save a grade.

To quickly test this, I took your sample and added another method to get the grades. The majority of the method is identical, meaning setting up the configuration and creating the logintool and login in.

The piece that changes is after confirming that the login is successful.

GradebookWSStub gradebookWSStub = new GradebookWSStub(ctx,
"https://"; + blackboardServerURL + "/webapps/ws/services/Gradebook.WS");

client = gradebookWSStub._getServiceClient();

options = client.getOptions();


// Next, setup ws-security settings
// Reuse the same callback handler
options.setProperty(WSHandlerConstants.PW_CALLBACK_REF, pwcb);
ofc = new OutflowConfiguration();
ofc.setActionItems("UsernameToken Timestamp");

options.setProperty(WSSHandlerConstants.OUTFLOW_SECURITY, ofc

List<ScoreVO> scores = new ArrayList<ScoreVO>();
GetGrades getGrades = new GetGrades();
ScoreFilter filter = new ScoreFilter();
filter.setUserIds(new String[]{"tjones"});

// 8 is the filter type for user id
GradebookWSStub.GetGradesResponse getGradesResponse = null;

try {
getGradesResponse = gradebookWSStub.getGrades(getGrades);
} catch (RemoteException e) {
LOGGER.error("Error getting grades: " + e.getMessage());

for (GradebookWSStub.ScoreVO score : getGradesResponse.get_return()) {"Found score: " + score.getId() + " with score: " + score.getGrade());

The call to getGrades() -> is successful but in my loop below it where I print out the score information, "getGradesResponse.get_return()" is always returning null. The user "tjones" does have graded items.

I was hoping if you could see what I'm doing wrong.
# Posted By Phil | 2/17/15 10:51 PM
Thanks for your project. I downloaded it, and get compiled in eclipse after I add all jar files that it needs. Finally, I got this error

2015-09-04 16:12:08,819 ERROR - There was an error in registering the tool: Couldn't find repository location '/usr/local/blackboard/config/axis2_client/modules'

Question: this bbws.modulePath is at blackboaord server site or at client site where registerproxytool installed?


# Posted By Jianrong Yu | 9/4/15 3:24 PM
BlogCFC was created by Raymond Camden. This blog is running version Contact Blog Owner