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.
Fact: WSDL is the cornerstone of the Universal Description, Discovery and Integration (UDDI) initiative spearheaded by Microsoft, IBM and Ariba.
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.
Fact: HTTP requests are usually allowed through firewalls; programs using SOAP to communicate can communicate with programs anywhere. Ariba, Commerce One, Compaq, Developmentor, HP, IBM, IONA, Lotus, Microsoft, SAP and UserLand proposed the SOAP Internet protocol to the W3C in May 2000.
> 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.
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.