VB.Net and GroupWise Soap Pt. 2 - Getting a Folder List
In my last post, I talked about accessing GroupWise via the SOAP services that they provide. Specifically, we looked at logging in. In this post we want to expand upon the application that we started and add some more functionality.
Our problem, continued from the last post was to figure out how to login and create a draft message in the user's Work in Progress folder that is a template of something the company uses currently in hard copy. In this article, I'm going to look specifically at how to do some work with the folders. This is necessary so that we can place our message in the correct folder once we create the draft message. I plan to do future articles on some of the other information that I find and that I figure out.
We will be building on the application that we started last time. If you haven't created the login procedures from Part 1, I suggest you do it now, we will need to login.
To start, let's add the controls to the form that we will use in this exercise. We need to add another button, name it btnListFolders, set the text to 'List Folders' and finally, set enabled to false (yes, false). Next create a multiline text box and name it txtResults (you may want to add a label to go with it.
Now let's also add a couple of helper functions that we can reuse them over and over. We want to add two functions, one called ReportStuff() and one called ToggleButtons() the are defined as:
Private Sub ReportStuff(ByVal sCurrentStatus As String)
txtResults.Text &= sCurrentStatus & vbCrLf
Private Sub ToggleButtons(ByVal bLoggedIn As Boolean)
If bLoggedIn = True Then
btnListFolders.Enabled = True
tslblCurrentStatus.Text = "Logged In..."
btnListFolders.Enabled = False
tslblCurrentStatus.Text = "Logged Out"
Basically, we just pass stuff to our report stuff so that we can track what's happening. It will print what we pass it to the text box. The ToggleButtons subroutine we'll call so that we can enable and disable buttons and give feedback regarding our login status.
We'll make some minor changes to our login and logout functions to incorporate our new helper functions. In LoginUser() add the following line just before the 'If 0 = resp.status.code then' line:
ReportStuff("Login status: " & resp.status.code.ToString())
and as the last line in the if then block we were just referencing, add the following line:
Finally, add the following line inside our if then block in LogoutUser():
Ok, now we're ready to add our folder functionality. We're going to look at two different pieces of functionality regarding folders, first, listing them all, and second, getting the ID of a particular folder. We'll create our listing function, then reuse it's code to create the other.
To get started, create a new subroutine, and name it GetFolders(). As is the pattern with GroupWise Soap objects, we'll create a request object, then pass it to a function and get back a response object. So let's start with our variables. Add the following to the top of your subroutine:
Dim flReq As New GWWS.getFolderListRequest()
Dim flResp As GWWS.getFolderListResponse
Now that we've created our objects, let's start populating them. It doesn't really take much to get a folder list back. Add the following to our subroutine:
flReq.recurse = True
flReq.parent = "folders"
flResp = wsGWBinding.getFolderListRequest(flReq)
Our settings simply tell the server we want to recurse and return all the folders, not just the direct children folders, and then we have to specify where to start by setting the parent folder. We want to start at the "folders" folder. That will give us ALL the folders, including the home folder. We then make the request to the server and get back a response.
Now we need to go through the folder list and list the folders. We'll just have the list pumped out to the txtResults box using our new ReportStuff function. First we need to check that our response wasn't somehow messed up and that we have a valid folder response object. Add a bit of reporting and an If Then as follows:
If IsNothing(flResp.folders) = False Then
This just checks that we aren't working with an empty object. Next, we'll add some additional reporting and set up a loop to go through our response object. Add the following:
ReportStuff("Listing the " & flResp.folders.Length & " folders found:")
For Each theFolder As GWWS.Folder In flResp.folders
Finally, we'll create a basic For Each loop and loop through all the folder objects in the folders collection. All that is left is for us to do our reporting for each folder we parse. Add the following reporting line:
ReportStuff(theFolder.name & " " & theFolder.description & _
" " & theFolder.id)
Call your GetFolders subroutine from your btnListFolders click event. We need to make sure that we don't check our folder list unless we're logged in, and that's where the toggle buttons comes in. We've already set the application to not allow you to click the List Folders button if we are not logged in. Run your application, login and then click the List Folders button. You should get a list of the folder names, and ID's. "But we asked for the folder description," you say. Sure, but most, if not all, of the folders don't have a description so it shows blank, and then we have a horribly cryptic folder ID at the end. This ID is what we need if we want to create an email in a specific folder. Passing the name of the folder doesn't work, we need to pass the folder ID.
With our GetFolders() sub working correctly, let's look at getting the ID for a specific folder. The Function to return the ID of a specified folder is basically the same as the one we created above, but without most of the reporting tied in. We'll create a new Function as follows:
Private Function GetFolderIDByName(ByVal folderName As String) As String
Now copy and paste our GetFolders() subroutine, and remove our reporting elements. We will also remove the existing code inside our For Each block. We'll replace it with an If Then that compares the folder's name with what we pass in. If they match, we return the folder's ID (not the name). Add the following lines in our For Each block:
If theFolder.name.ToLower() = folderName.ToLower() Then
Now we just need to hook it up. Add a line to your btnListFolder's click event (or replace your line that calls GetFolders()) as follows:
ReportStuff(GetFolderIDByName("Work In Progress"))
Run your app, Login and press your List Folders button. We get the ID of the Work in Progress folder.
Using the web services for GroupWise isn't exactly intuitive. Once you get an understanding of the Request/Response model it gets much easier to use. Documentation could still be a little better letting us know what each of the properties and methods are and do specifically, but we work with what we have. In the next part I think we'll look at actually creating a message now that we can reference the folders by ID.