Developing to the Novell GroupWise® SOAP/XML Protocol

Tim Draper

GroupWise Development

Novell Inc.

Agenda

Technologies and Architecture Overview

Using the GroupWise SOAP Protocol

Summary

Developer Resources

What is the GroupWise SOAP Protocol?

The GroupWise SOAP protocol provides direct access to the Post Office Agent (POA) to retrieve GroupWise data. It is a server-side protocol that uses Web Standards to package and deliver requests from SOAP clients and responses from GroupWise POAs.

Summary

Direct access to Post Office Agent

Uses Web Standards

Available in next GroupWise Release (summer 2005)

Web Standards

Client

GroupWise

POA

Web Standards

Web Standards

Web Standards

Web Standards

SOAP Protocol Features

Authentication: User, Trusted Application, Proxy

Create, Retrieve, and Modify

Message Items

Folders and Shared Folders

Address Books and Address Book Items

Events

Rules

Etc...

SOAP

What are GroupWise Events?

In the next release of GroupWise, SOAP clients can be be notified when changes occur to a mailbox.

Overview

SOAP clients register for desired GroupWise events

(i.e. item created, folder deleted, etc...)

SOAP clients are notified when a registered event occurs

SOAP clients retrieve changes in mailbox

SOAP

Web Standards

Client requests and Server responses are packaged with the following Web Standards:

XML

SOAP

HTTP

Web Standard - XML

XML describes the data and meta-data.

<loginRequest>

<userName>tdraper</userName>

<password>myPassword</password>

</loginRequest>

Web Standard – SOAP Envelope

SOAP is an XML based document that wraps XML data.

SOAP Envelope

SOAP Header

SOAP Body

(XML data)

Web Standard - HTTP

HTTP is the transport used to move the SOAP Envelops and XML data from computer A to computer B.

SOAP Envelope

(XML data)

HTTP

Request/Response Lifecycle

HTTP wrapping

SOAP wrapping XML

SOAP Client

POA

GroupWise

POA

GroupWise User Database

Defining GroupWise Data

Questions:

How does computer B understand a request from computer A?

What does a date look like?

Is it a string or a number?

How do we define GroupWise data?

Answer:	XML schemas

Solution: XML Schemas

They express shared vocabularies and allow machines to carry out rules made by people. They provide a means for defining the structure, content and semantics of XML documents.

W3C

Summary:

Rules that define a well formed XML document

Define allowed structures and content in XML documents

XML

Example

Schema definition of a username:

<xs:element name="username" type="xs:string" />

XML instance of a user name:

<username>John Doe</username>

GroupWise Schemas

Types.xsd

Defines GroupWise data types and structures

Methods.xsd

Define actions (i.e. Login)

Events.xsd

Broadcasts changes to a mailbox

SOAP Envelope

SOAP Envelope

SOAP Header

SOAP Body

(XML data)

Login Request

<?xml version="1.0" esncoding="UTF-8" standalone="no" ?>

<SOAP-ENV:Envelope

xmlns:SOAPSDK1="http://www.w3.org/2001/XMLSchema"

xmlns:SOAPSDK2="http://www.w3.org/2001/XMLSchema-instance"

xmlns:SOAPSDK3="http://schemas.xmlsoap.org/soap/encoding/"

xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Body SOAP-ENV:encodingStyle="">

<loginRequest>

<types:auth xmlns:types="http://schemas.novell.com/2003/10/NCSP/types.xsd"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="types:PlainText">

<types:username>u4</types:username>

<types:password>u4</types:password>

</types:auth>

</loginRequest>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

Coding Choices

First Choice:

Directly code HTTP and SOAP wrappers for each client request

- Time Consuming

Second Choice:

Use a Web Services Description Language – WSDL

- Faster and Easier

- Preferred

Web Services Description Language

Best Choice: WSDL

Advantages:

- Development Frameworks abstracts away the complexities of HTTP, SOAP and XML

- Method calls on local objects give you distributed system capabilities

Development Choices

Programming languages or frameworks that Support Web Services

Java

Many different vendor implementations

Microsoft .Net

C++

C#

Visual Basic

Mono – Microsoft .Net on Linux

WSDL Usage

Development Frameworks can reduce and simplify developers work load.

Development Frameworks provide the following:

- Import a WSDL file for a service

- Creates a library for the service

- The library abstracts away the complexities of HTTP, SOAP, and XML

Hands On Overview

We will:

Use an existing Java library created for this class called gwws.jar

Modify a Java client to access GroupWise

Login

Get Folder List

Get Items

Get Item

Send new Item

Hands on: Login to GroupWise

Login Request

Method: LoginRequest

Parameters:

user name

user password

language

Login Response

Method: LoginResponse

Returns:

session id

Required by all other methods in this session

user information

status

Return code – 0 for success

Hands on: Get the Folder List

Get Folder List Request

Method: GetFolderListRequest

Parameters:

parent

“folders” to get all folders from the root

Otherwise, parent folder id

recurse

“1” returns all sub folders

Get Folder List Response

Method: GetFolderListResponse

Returns:

Folders

Folder name, isSystemFolder, etc...

status

Return code – 0 for success

Hands on: Get Items

Get Items Request

Method: GetItemsRequest

Parameters:

container id

(a.k.a. - Folder id)

Get Items Response

Method: GetItemsResponse

Returns:

Items

name, id, subject, etc.

status

Return code – 0 for success

Hands on: Get an Item

Get Item Request

Method: GetItemRequest

Parameters:

id of item

Get Item Response

Method: GetItemResponse

Returns:

Item

name, id, subject, etc.

status

Return code – 0 for success

Hands on: Send a New Item

Send Item Request

Method: SendItemRequest

Parameters:

subject

item type: mail, appointment, note, etc.

recipients

message

etc...

Send Item Response

Method: SendItemResponse

Returns:

status

Return code – 0 for success

Development Resources

HTTP: http://www.w3.org/Protocols/

SOAP: http://www.w3.org/TR/soap/

XML: http://www.w3.org/XML/

WSDL: http://www.w3.org/TR/wsdl

XML Schemas: http://www.w3.org/XML/Schema

2003-12-08T12:43:39