Please Pass the S.O.A.P.
Articles and Tips:
01 Feb 2006
In the business world when you need answers or you want get to the bottom of a particularly difficult issue, a face-to-face meeting with your key players often gets the best results. It's that direct eye contact and being able to watch someone's body language that helps you cut to the chase and get the information you need to make the right decisions that lead to success.
Similarly, when it comes to getting a handle on what's going on in your GroupWise information stores, a direct approach can often enhance your efforts. No, I'm not saying that all your IT team meetings need to happen face to face. While that can be a good thing, I'm talking about the new Simple Object Access Protocol (SOAP)/XML-based Web service in Novell GroupWise 7 that enables you to directly access your GroupWise Post Office Agents programmatically, or through the back door using code.
The Scoop on SOAP
The GroupWise Web Service enables direct client-to-Post Office Agent communication, allowing you to easily see, use and manipulate data in users' mailboxes. While the GroupWise Object API provides this same functionality, it uses a Component Object Model (COM) interface, which means that it's only available on Windows. As a standards- based solution that utilizes SOAP, the GroupWise Web Service facilitates cross-platform development. Furthermore, because the GroupWise Web Service is a server-side interface, it makes it ideal for multithreaded, high-performance server applications.
The goal of SOAP is to provide programs an easy way to communicate with each other using XML. It was developed by the XML Protocol Working Group as part of the WC3 Web Services Activity. (WC3 stands for the World Wide Web Consortium, which defines and develops specifications, guidelines, software and tools for the Web.)
SOAP is defined as a lightweight XML-based protocol for the exchange of information in decentralized, distributed environments. The SOAP protocol consists of three main parts:
a SOAP envelope that defines a framework for describing what is in a message and how to process it
SOAP-encoding rules that define a serialization mechanism that can be used for expressing instances of application-defined data types
a SOAP RPC convention for representing remote procedure calls and responses
Essentially, SOAP, XML and HTTP work together to enable and facilitate communication between Web services and service requesters, independent of platform. HTTP is the transport. SOAP is the container. XML is the data. It's through this SOAP, XML and HTTP combination that GroupWise 7 enables and facilitates platform- independent communication between service requesters and the GroupWise Web Service.
GroupWise has SOAP listeners that you can enable on your different GroupWise Post Office Agents. When enabled, the GroupWise Web Service, or SOAP, listens for requests from SOAP clients. These requests provide the means for SOAP clients to access client data stored in GroupWise Post Office Agents. These requests can include login to a user's mailbox; getting address books and address book items; getting the folder list; and accessing proxy, shared folders and other client actions.
An Open Heart
While the heart of the GroupWise Web Service is the industry standards that it leverages--HTTP, XML, SOAP and Web Services Description Language (WSDL)--it's the GroupWise use of WSDL that makes it so easy for administrators and third-party developers to take advantage of this new Web service interface for GroupWise.
As its name suggests, WSDL is a language used to describe a Web service. It is currently in the WC3 proposal stage, but it seems to have already been adopted as an industry standard for reducing the time it takes for developers to create SOAP/XML service requester applications.
A WSDL document is an XML file that has three functions. It:
describes what operations a Web service can perform
tells how to talk to the Web service
shows the methods that a Web service exposes.
You can leverage this capability with the GroupWise WSDL and GroupWise Web Service if you use an IDE or application framework that can compile a WSDL and schema into its Web Service library.
Think of it like this: WSDL is to Web services what .h files are to C++. If you want to help someone understand how to use your C++ classes, you give them your .h files. Even though they might not have your implementation, they can interface with it because they have your class declarations. A WSDL document likewise gives you the information your applications need to understand and use a particular Web service. So referring to the three functions just stated, the GroupWise WSDL a) describes what operations the GroupWise Web Service can perform, b) tells how to talk to the GroupWise Web Service, and c) shows you the methods that the GroupWise Web Service exposes.
In short, the GroupWise WSDL makes it easy for you to use the GroupWise Web Service to get to and manage the data in your users' mailboxes. Its goal is to eliminate the need for you to understand or deal with the complexities of XML, SOAP and HTTP as you take advantage of the GroupWise Web Service.
Before You Start
Before you can start developing your own SOAP GroupWise service requester or client, you need to take care of a few housekeeping items. First, make sure you have the following basics:
GroupWise 7 or later
an Integrated Development Environment (IDE) framework that supports Web services such as Java, .Net, Mono (open source implementation of .Net on Linux), or gSOAP
Java developers can choose from a variety of implementations or frameworks, including Sun's Web Services Developer Pack with NetBeans IDE 4.1 or later and J2SE5.0 or later.
.Net developers can use Microsoft .Net 2003 or later.
GroupWise Web Service (SOAP) Novell Developer Kit
Let's Get Going
Now, complete the following steps:
Review the materials in the GroupWise Web Service (SOAP) Novell Developer Kit. Start with the readme.1st file. It provides brief overviews and the locations of key documents and files contained in the Novell Developer Kit, including additional readme files, SDK documentation, schemas and more.
Java developers need to read the readmeJava.sxw file and .Net developers should read the readmeMSNET.sxw file to get specific information on setting up the development frameworks to work with GroupWise WSDL.
Enable SOAP on your GroupWise Post Office Agent from ConsoleOne: select the desired Post Office Agent, select Agent Setting from the GroupWise tab, and mark Enable SOAP. (See Figure 1.) You can also enable SOAP through the command line or a configuration file.
Figure 1: You can enable the SOAP listener on your GroupWise Post Office Agent from within the Agent Setting under the GroupWise tab in ConsoleOne.
Have It Your Way
The Novell Developer Kit for the GroupWise Web Service (SOAP) contains the GroupWise WSDL and schema files for Java, Microsoft .Net and other development frameworks. So whether you work in Java, Mono, .Net, or another framework, if you want to use GroupWise WSDL, it's a simple matter of importing the GroupWise WSDL document into your framework environment.
To import the GroupWise WSDL into a .NET framework (using Visual Basic), do the following:
Select New|Project from within your .Net framework.
Select Visual Basic as your development language.
Open Solution Explorer and click on the project name.
Select Add Web Reference and then enter the location of the groupwise.wsdl file. (See Figure 2.) Ensure that the XML schemas types.xsd and methods.xsd are in the same directory as groupwise.wsdl.
Name the Web Reference.
To import the GroupWise WSDL into a Java framework do the following:
From within the NetBeans IDE, select File|Open Project and open the project directory at /netbeans/javaClient.
A dialog box will likely appear informing you that your project is not set up correctly. The following steps tell you how to resolve the problems:
Click the JavaClient project and select Resolve Reference Problems.
When the Resolve Reference Problem appears, highlight "GWWS library could not be found" and click Resolve.
Select "New Library" and name it GWWS.
Add the GroupWise WSDL library to your newly created library: select the Classpath tab and click Add JAR/Folder. Then highlight the /wsdl/dist/lib/gwws.jar file and click OK. (See Figure 3.)
On both the Sources and JavaDoc tabs, add the directory /wsdl/java/build/src. At this point, a dialog will show that GWWS has been resolved, but it might also show that JWSDP still needs to be resolved. This means you need to add the Java Web Services Developer Pack jar files into your development environment. To do this, create a new library for it in much the same way you did for the GroupWise WSDL. You can find the details for this process in the readmeJava.sxw file in the Novell Developer Kit.
Figure 3: To import the GroupWise WSDL into a Java Integrated Development Environment, create a new library and add the GroupWise WSDL gwws.jar file into that newly created library.
Note: Whether you're working with a Java or .Net framework, you should review the Developer Kit's readme files specific to your environment for setup and configuration details.
Digging In
When you import the GroupWise WSDL into your development framework, it automatically generates a GroupWise Web Service library that allows you to easily make calls directly to the Post Office Agent. For example, if you want to log in to GroupWise, simply use the local "login" method and objects that have been created by the framework's WSDL compiler. You don't have to deal with the underlying details of working with SOAP, packaging XML documents, parsing XML or using HTTP. Once the GroupWise WSDL document is imported into your framework, those details are taken care of by your application framework.
To see how the GroupWise WSDL simplifies your development efforts in interfacing with the GroupWise Web Service, see Cut and Paste.
The Novell Developer Kit contains even more extensive sample programs for using GroupWise WSDL methods for things such as logging into the GroupWise Web Service, and getting folder lists and mailbox items. In addition to sample code, the Developer Kit contains PDF documentation files on the methods and objects for the GroupWise SOAP protocols and GroupWise Events. The developer kit also provides the XML schemas that help you understand what methods can be used on the GroupWise Post Office Agents as well as show you what objects GroupWise expects for certain methods.
Even though the goal of GroupWise WSDL is to make it easier to create programs that directly access Post Office Agents, you don't have to use the WSDL. If you're proficient with XML, SOAP and HTTP, you can do all the underlying low-level programming yourself. Just stick to the schemas provided in the Developer Kit. It will take more work on your part, but it might give you a little more control or flexibility to accomplish what you want.
Cut to the Chase
By allowing you to interact directly with Post Office Agents, the GroupWise Web Service enables you to easily and quickly create cross-platform solutions that make it simple for administrators and developers to view, manage and manipulate the information stored in users' mailboxes. You can create custom applications that, from outside of GroupWise, can retrieve folder lists, do busy searches, manage proxy rights, generate reports, view items, deal with junk mail or a variety of other tasks that extend an administrator's capabilities.
No matter what you want to do, the bottom line is that the Novell GroupWise Web Service gives you a new option for getting direct access to the data stored in your users' mailboxes. It uses industry standards to simplify development efforts, reduce development time and provide cross-platform support. But best of all, it let's you programmatically cut to the chase, bringing you face to face with the mailbox information you need to solve your problems and produce the results you want.
Other Helps
One of the particularly easy-touse helps in the Developer Kit is a javadocs API document file called index-all.htm located in the folder /Java/netbeans/wsdl/build/src/. It gives details on the GroupWise Web Services libraries, constructors, fields and methods. The javadocs file has several sections:
Package provides a list of classes and interfaces for each package, with a summary for each package. It also includes categories for Enums, Exceptions, Errors and Annotation Types.
Class/Interface provides class/interface descriptions, summary tables and detailed member descriptions for each class, interface, nested class and nested interface.
Annotation Type includes declarations, descriptions, required element summaries, optional element summaries and details for each Annotation Type.
Enum provides a separate page for each Enum with sections for declarations, descriptions, constant summaries and constant details.
Tree (Class Hierarchy) contains a Class Hierarchy page for all packages, plus a hierarchy for each package. Each hierarchy page contains a list of classes and a list of interfaces.
Index contains an alphabetic list of all classes, interfaces, constructors, methods and fields.
Serialized Form each serializable or externalizable class has a description of its serialization fields and methods. This information would be of interest to reimplementors, not developers using the API.
Constant Field Values lists the static final fields and their values.
Listening In
In addition to letting you access the data in your Post Office Agents, the GroupWise Web Service also lets you listen for events that occur there. GroupWise uses event records to track event data on a user-by-user basis. Event records are stored in each user's individual database. SOAP clients can register with the GroupWise Web Service so they are notified when certain events occur. In other words, by using individual user keys, you can be notified when events related to a certain user occur. You can register for notification on specific events, as well as for events that take place within a certain time.
For example, you can create an application that notifies you when certain items are deleted from a user's mailbox. Now that you know how to listen for GroupWise events, you can create powerful and efficient applications that eliminate your laborious task of regularly dredging the mailbox for information, and looking for changes during periodic comparison checks.
Cut and Paste
The following Java code gets a folder list for a GroupWise user's mailbox:
// The views are the XML elements or fields that the POA will return
String view = new String("name folderType");
// Create a response object
m_folderListResponse = new GetFolderListResponse();
// Call the POA to get the folder list
// 1st parameter: "folders" means to get all the folders from the root of the mailbox
// 2nd parameter: elements to return in the response
// 3rd parameter: return all the folders in the mailbox
// 4th parameter: return imap folders
// 5th parameter: return nntp folders
// 6th parameter: session id
m_folderListResponse = m_main.getGWService().getFolderListRequest("folders", view, true, false, false, m_main.getSessionId());
// The response will have the folders. If there is not a problem, the return code will be 0
if(m_folderListResponse.getStatus().getCode() == 0 )
{ // Success getting folder list }
* Originally published in Novell Connection Magazine
Disclaimer
The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.