Using Blackboard Learn 9 Web Services - Part 2 Learning About The Web Service Classes And Methods

Introduction

Blackboard Learn 9.1 provides many different web service classes and those class have numerous methods that you can use to get data out of the Blackboard system and to update/add to data in the Blackboard system.  To effectively use the web service classes you must review what each class can do and how your web service client application can use a particular web service class.  In part 2 of this tutorial series on Blackboard web services, I'll review some of the Blackboard web service classes and how you can find out more information about each class and its methods.

Determine What The Blackboard Web Services Can Do

In part 1 of this tutorial we reviewed how to register the proxy tool and authorize it to use specific web services and methods. If you examine the code for the registerproxytool project (see part 1) you'll notice that the program uses the Blackboard Context web service to register the proxy tool with the Blackboard installation.  The first step in determining how to use the Blackboard web services is to research what the web services can do and which ones your application will need to use.

How can you learn about the different Blackboard Learn 9.1 web services and what those web services can do?

If you have a Blackboard support account you can login to Behind The Blackboard and then go to:

https://behind.blackboard.com/s/sysadminas/refcenter/docs/details.Bb?DocumentID=3733&pid=100000&rid=5797&dt=

The above document is the JavaDoc for the Blackboard Learn 9.1 web service classes.  You can also get the JavaDoc by logging in to your Blackboard installation as a system administrator and going to System Admin – Web Services (under the Building Blocks section).  There you'll see:

The above are a list of web service classes your Blackboard installation provides.  If you click on the down arrow next to a web service class name (e.g. Context.WS) and then click on Operations you'll then see a list of methods for that web service that you can call.  You may also click on the down arrow next to the web service name and select Download Documentation.  That action will download a zipped file containing all the JavaDoc for that particular web service.

You'll have to read through the JavaDoc and/or the list of operations for each web service to determine what each web service class does, generally how to use the web service class, and what methods you need to use to perform a particular task.  Unfortunately, as of August 2010, Blackboard hasn't published a web service's user guide that details what each web service can be used for and how to use it.  But reading through the JavaDoc should provide you with enough details so you can determine which web service class and methods you need to use to get specific information out of Blackboard or to update/add information into Blackboard.

Blackboard Web Services

Below is an incomplete list of the major Blackboard web service classes and what each class can do.

It's important to understand that your client application must first use the Context web service to initialize a session with your Blackboard installation and then to use the Context web service to login.  After a successful login, your application may then use the other web services and their methods that your login is authorized to access (see below).

Authorizing The Proxy Tool For Specific Web Services And Operations

If you review part 1, we used a Java application (registerproxytool) to register a proxy tool that can be used to login to Blackboard web services and then make calls upon those web services.  A Blackboard administrator had to authorize the proxy tool and make it available.  When a proxy tool registers with your Blackboard installation it requests access to specific web services and methods of those classes. 

If you examine the JavaDoc for the Context web service's registerTool method you'll see that one of the arguments to that method is requiredToolMethods - An array of String objects (web service method names) that you will use when logged in as a tool.  But how do you know how to format each string in the array?

If you examine the Spring configuration application_context_BBWS.xml file in the registerproxytool project (see Part 1) you'll see this node:

                <property name="toolMethods">

                               <list>

                                             <value>Context.WS:emulateUser</value>

                                             <value>Context.WS:logout</value>

                                             <value>Context.WS:getMemberships</value>

                                             <value>Context.WS.getServerVersion</value>

                                             <value>Context.WS.initialize</value>

                                             <value>Context.WS.loginTool</value>

                                             <value>Context.WS.registerTool</value>

                               </list>

                 </property>

The above is using Spring to create an Array of String objects that will be assigned to the toolMethods array.  The toolMethods array object will be passed as an argument to the registerTool method of the Context web service.  So the above is specifying that this proxy tool wants to access the Context web service and the methods emulateUser, logout, getMemberships, etc.

The first part of the String format is the name of the web service including .WS (e.g. Context.WS).  You can find all the web service names by going to System Admin – Web Services (under the Building Blocks section).  You can find the operations of a web service by clicking on the down arrow next to the web service name and selecting Operations.  For example below are the operations for the Context web service:

So the second part of the String is the operation name as shown above (e.g. emulateUser).  Thus the complete value for one of the Strings in the toolMethods array is Context.WS:emulateUser.

If your proxy tool hasn't requested a specific web service and method and been authorized by the System Administrator then you will get a null response back from the Blackboard server.

If you recall from part 1, you may only register the same proxy tool once.  If you need to change the web services and methods the proxy tool needs to use then you must first delete that proxy tool from system admin – building blocks – proxy tools.  Then you can register the proxy tool again with a new list of web services and methods that the proxy tool needs to use.

Summary

Before you can build a client application that will use Blackboard's web services you must learn about the different web services and what each can do.  Then you will know which web services your client application must use to accomplish its tasks.  You must also ensure that the proxy tool you are using to login has the rights to call upon those web services and their methods.  Reviewing the JavaDoc for each web service and reading through the comments for each method will help you learn about the web services and how to use them.

In part 3 of this series I'll cover how to generate the client classes after you've determined which Blackboard web service classes your application needs to use.