Using Blackboard Learn 9 Web Services - Part 4 Getting, Creating, Updating, Deleting Users
Introduction
Blackboard Learn 9.1 provides a User web service that you can use to get information about one or more Blackboard users, create one or more new users in your Blackboard system, and delete existing users. Currently there is a bug in the User web service that prevents using the service to update the information for a current Blackboard user. This tutorial will review how to use the User web service. You should review the previous tutorials in this series prior to reading this part.
Example Application
You can download the example application from /blackboard/updateaddblackboarduser.zip. The download is an archived Eclipse project created using Eclipse 3.5 and Maven 2. The program demonstrates how to get a Blackboard user's information if you know the username, how to create a new Blackboard user, and how to delete an existing user.
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, run the JUnit tests, and how to run the main class. 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 use.
Proxy Tool
To use the User web service, the proxy tool you use for logging in (see part 3 of this tutorial) must be authorized to access the User web service and its methods. The example application includes a class, RegisterProxyToolApp, that you may use to register a new proxy tool with the appropriate authorizations. Remember, after registering a new proxy tool, a Blackboard system administrator must authorize the tool.
User Web Service Client Class
To make calls upon the User web service you'll need a User web service client class. In part 3 of this series I reviewed how to generate the web service client classes using Axis2 and the WSDL file provided by the web service. The example application includes the generated UserWSStub class, which is the User web service client class. Recall that the client class includes the methods that enable interaction with the web service and the additional data types the web service requires.
User Web Service - Get Blackboard User
The User web service has a getUser method that you can use to get information about one or more users. You can search on different user attributes such as user id or username to find specific users. In the example application, I want to find a Blackboard user with a specific username. In the example application, if you examine class BlackboardUserServiceImpl method getBlackboardUser you'll find this code:
UserFilter userFilter = new UserFilter();
userFilter.setFilterType(6);
userFilter.setName(new String [] {username} );
GetUser getUser = new GetUser();
getUser.setFilter(userFilter);
The above code first creates a UserFilter object that I use to specify how I want the User web service to search for the Blackboard user. I set the filter type to 6, as 6 is the value to search by username. You have to read the JavaDoc for the UserFilter class's setFilterType method to find the different integer values you can use to specify how the User service should search.
Note the argument to the setName method is an array of String objects whose values are the Blackboard username for the users I want to find. In the example application I just want to find a single user, so the array has just one element. If you want to find multiple users, you can have multiple usernames in the array used as the argument to setName.
The GetUser object above is used to setup all the criteria, including the filter criteria that we want the User web service's getUser method to use.
After creating the UserWSStub (the User web service client class) and setting up it's security options, you'll find this code in method getBlackboardUser:
GetUserResponse getUserResponse = userWSStub.getUser(getUser);
UserVO [] blackboardUsers = getUserResponse.get_return() ;
Processing the result of calling the getUser method provides an array of UserVO objects. The UserVO class is used to store the values about a specific Blackboard user. You can consult the JavaDoc for UserVO to see all the get methods you can call to get data about a Blackboard user (see part 2 for how to find the JavaDoc for the Blackboard web services). One thing about the UserVO that perplexed me at first was how to get the user's first and last name. That data, along with the user's email, address, and other information is stored in another object of type UserExtendedInfoVO. So to get the user's first name you would call: userVO.getExtendedInfo().getGivenName().
User Web Service - Save New Blackboard User
The User web service has a saveUser operation. You can use this method to save a new user in your Blackboard system. In class BlackboardUserServiceImpl, method saveBlackboardUser is this code
SaveUser saveUser = new SaveUser();
saveUser.addUser(blackboardUser);
SaveUserResponse saveUserResponse = userWSStub.saveUser(saveUser);
String [] userIds = saveUserResponse.get_return() ;
The SaveUser object is used to specify all the UserVO objects that we want to save as new users in Blackboard. You can use the addUser method to add each UserVO object one at a time or you can use the setUser method that takes an array of UserVO objects as an argument. The result of calling the User web service's saveUser method is an String array with each element having the user id value for the user added. If the user id value is null, then that user was not added to the Blackboard system.
User Web Service - Delete Blackboard User
The user web service has a deleteUser operation. You can use this method to delete an existing user in your Blackboard system. In class BlackboardUserServiceImpl, method deleteBlackboardUser is this code
DeleteUser deleteUser = new DeleteUser();
deleteUser.setUserId( new String [] { blackboardUserFound.getId() });
DeleteUserResponse deleteUserResponse = userWSStub.deleteUser(deleteUser);
String [] userIds = deleteUserResponse.get_return() ;
The DeleteUser object is used to specify which users we want to delete. You provide an array of Strings, where each element has the user id value for the user you want to delete. The result of calling the User web service's deleteUser method is a String array, where each element is the user id value for a user that Blackboard deleted. A null value indicates that no user was deleted.
User Web Service - Update Blackboard User
As of Blackboard Learn version 9.1.452.0 there is a bug in the User web service's saveUser method. To update an existing user you should be able to provide saveUser with a UserVO object that represents an existing user. The saveUser method should update that existing user with the values of the provided UserVO object's instance fields. Unfortunately this User web service operation is not working correctly and should not be used. The example application BlackboardUserServiceImpl includes an updateBlackboardUser method that demonstrates how to use the User web service saveUser to update an existing Blackboard user.
Summary
The User web service provides operations that allow you to get information about one or more users out of your Blackboard system. You can also use it to create new users and to delete existing users. Once the bug is fixed, you'll be able to use the User web service to update information for existing users.
I just wanted to let you know that I'm on release 9.1.482.2 and can confirm that the "saveUser" bug still exists - but I had to modify your junit test slightly before I could actually get to that point. In BlackboardUserServiceTest.java I had to add this code:
UserExtendedInfoVO extInfo= new UserExtendedInfoVO();
extInfo.setEmailAddress("[email protected]");
blackboardUser.setExtendedInfo(extInfo);
in between the "blackboardUser.setName(username);" and the beginning of the try block. Otherwise, there's no email address set for blackBoardUser - which results in a TargetInvokationException.
Still, I'm hoping that this will be a non-issue for me because I'll be implementing an LDAP server along with Bb 9.1. This way the user passwords won't be stored in Blackboard anyway.
Just wondering if you've ever got a GET_COURSE_BY_SEARCH_KEYVALUE [aka courseFilter(5)] search to work? All I can manage is the error message: [WSFW000]null.
In my case, I'm trying to look for part of a course's name (the number 48072) . My code basically looks like this:
CourseFilter courseFilter = new CourseFilter();
courseFilter.setFilterType(5);
courseFilter.setSearchKey("CourseName"); //as described in the CourseFilter API
courseFilter.setSearchOperator("Contains"); //as described in the CourseFilter API
courseFilter.setSearchValue("48072"); //my search value
Long the_time = Long.parseLong(String.valueOf(System.currentTimeMillis()).substring(0, 10)); //10 digit Long - seconds precision
courseFilter.setSearchDate(the_time);
courseFilter.setSearchDateOperator("LessThan"); //as described in the CourseFilter API
GetCourse getCourse = new GetCourse();
getCourse.setFilter(courseFilter);
CourseWSStub courseWSStub = createCourseWebServiceObject();
GetCourseResponse getCourseResponse = null;
try {
getCourseResponse = courseWSStub.getCourse(getCourse);
} catch (RemoteException e) {
logger.error("Unable to get course response: " + e.getMessage());
}
The soap envelope that gets created with the above code looks like this:
<?xml version='1.0' encoding='utf-8'?>
<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">;
<soapenv:Body><ns3:getCourse xmlns:ns3="http://course.ws.blackboard">;
<ns3:filter>
<ns1:filterType xmlns:ns1="http://course.ws.blackboard/xsd">5</ns1...;
<ns1:searchDate xmlns:ns1="http://course.ws.blackboard/xsd">132710033...;
<ns1:searchDateOperator xmlns:ns1="http://course.ws.blackboard/xsd">LessThan&...;
<ns1:searchKey xmlns:ns1="http://course.ws.blackboard/xsd">CourseNam...;
<ns1:searchOperator xmlns:ns1="http://course.ws.blackboard/xsd">Contains&...;
<ns1:searchValue xmlns:ns1="http://course.ws.blackboard/xsd">48072<...;
</ns3:filter>
</ns3:getCourse>
</soapenv:Body>
</soapenv:Envelope>
Also, here's a quick tip: You'll notice that I set my search date up to work like the Bb Admin interface; using the current system date/time and looking for backward using the "LessThan" search operator. Another way that I found to do this is to simply set the search time to 0 (the Epoch) and look forward using the "GreaterThan" search operator:
courseFilter.setSearchDate(new Long(0));
courseFilter.setSearchDateOperator("GreaterThan");
Works just as well, but is less code - no need to do all of the System Time conversions.
Thanks for being really the only resource as we're trying to implement some Bb webservic stuff with CF9.
We're currently stuck trying to display a list of a user's courses as links directly to the course shell. Wher we die is Organizations. We'd really NOT like to render the Orgs for people , only the Courses. We're trying to use filter 5 and the getCourseServiceLevel method but not really returning anything. Have used that method before? And why might Organizations break our application output?
GetCourseResponse getCourseResponse = courseWSStub.getCourse(getCourse);
CourseVO [] courseVOs = getCourseResponse.get_return() ;
courseVOs is null, throws NullPointException.
thanks
Which class and line numbers are your referring to? I could not find the code you cite in the example application for this article.
We are exploring Bb WS to enroll users and courses.
However one thing noticed here is that to enroll any user in a course using saveCourseMembership of the CourseMembership WS requires us to set the PKID (Bb internal ID) for the course and user. We do not have those values and just the course ids and usernames of students.
We can get these values by doing a GET before SAVE but that would be inefficient for bulk updates.
Is there a way to enroll users using the course ids and student usernames?
Thanks
Check out the CourseMembership web service API to see if there are any over-loaded methods you could use to enroll a student into a course without having to know the PKIDs. I don't know of any.
Also, my recommendation would be to NOT use the CourseMembership web service to do large number of enrollments. Rather use one of the new data integration methods introduced with BB Learn 9.1 SP 7.
Bruce
We are looking at the new data integration methods as well.
As we dont have the standard SIS supported by these we are are trying to automate the flat file integration.
We were able to do so using Http POST, however it looks like we dont get any response back from the POST even on failure.
Can you suggest anything for this?
Thanks,
Contact me at bruce AT phillips . name
Bruce
i have created a web service it is working fine on blackboard learn but when i uploaded it to blackboard saas it get failed because of the insert query in it. Can any one help!