Consuming an External Web Service with Domino 6
Using the SOAPConnect for LotusScript package, developers can create Domino applications that can consume an external Web service and return the resulting data. This package, coupled with the Domino Designer tools, provides an easy-to-use mechanism that can be integrated into new and existing Domino 5 or 6 applications without the need for Java programming or the requirement of an external application server.
by Jeff Gunther
June 12, 2003
What is a Web service?
Web services give organizations the ability to extend existing business processes as published services. These services allow developers to loosely couple software components while easing the integration effort to exchange information between applications. Unlike traditional Domino Web-based applications, Web services contain no user interface for end-user interaction, but provide a unified way to execute processes and exchange data.
Web services are based on three technology standards:
The eXtensible Markup Language (XML), the enabling force behind Web services, is not a programming language or API but rather a platform-independent way to structure data. The syntax of XML makes it easy to programmatically manipulate textual data while still allowing it to be easily understood by humans. Web services use XML as the standard to provide communication between networked devices.
The Simple Object Access Protocol (SOAP) provides developers with a platform-independent mechanism to remotely invoke methods on distributed objects. The communication glue of a SOAP message uses XML for describing the object, method, and arguments to execute. Both clients and servers can implement and use SOAP. In this case, the SOAPConnect for LotusScript package provides an easy to use implementation that shields the developer from handling low-level XML.
The Web Service Description Language (WSDL) defines the available ports and operations for a particular Web service. You can think of a port as an interface and an operation as a method to be called on a particular object.
Book Catalog Scenario
Before I review the code and implementation details of how to use SOAPConnect for LotusScript, let's review the purpose and structure of the included sample database. The sample database is a short book catalog highlighting various gardening books. The goal of this database is to provide users with a way to receive up-to-date pricing on any book within the catalog. The database contains one form called Book that highlights the details about each book in the catalog. The Book form consists of five fields that describe each book: the book's title, the book's cover image, the book's author, the ISBN number, and the publisher. Users can browse the list of available books via a Web browser using the All Book view as shown in Figure 1.
As you'd expect, once a book has been selected in the view, the user is presented with that particular book's details.
Figure 2. Details for a particular book
As with most online retailers, the price of books fluctuates given demand and availability. The Get Price button allows users to receive an up-to-date price using the power of a Web Service from Barnes & Noble and the SOAPConnect for LotusScript package.
Installing SOAPConnect for LotusScript
The SOAPConnect for LotusScript package is available for download at the end of this article. In order to test the sample database or use the SOAPConnect for LotusScript, your environment must meet the following minimum requirements:
Lotus Notes Client, release 5.0.7a or later
Lotus Domino Designer, release 5.0.7a or later
Lotus Domino Server, release 5.0.7a or later
Although the SOAPConnect for LotusScript package doesn't require the developer to write any Java code, the package uses a Java agent underneath the covers to invoke the external Web service. Unfortunately, the Java agent uses an implementation of Apache's SOAP that requires a different version of the Java XML parser than the one installed as part of Notes and Domino. Following the steps below could affect other databases, so it's highly recommended that you perform these steps in a test or development environment.
To install on the Domino Designer, complete the following steps:
Unzip the SOAPConnect for LotusScript package in the directory C:\SOAPConnect.
Rename file XML4j.jar that is installed in the Notes program directory (by default C:\Lotus\Notes\XML4j.jar ) to XML4j.jar-hidden.
Copy all files in directory C:\SOAPConnect\ProgramDir to your Notes program directory (by default C:\Lotus\Notes ).
Copy all files in directory C:\SOAPConnect\DataDir to your Notes data directory (by default C:\Lotus\Notes\data ).
Rename file XML4J.jar that is installed in Designer's Java directory (by default C:\Lotus\Notes\data\domino\java ) to XML4j.jar-hidden. Then copy all files in directory C:\SOAPConnect\ProgramDir to your Designer Java directory (by default C:\Lotus\Notes\data\domino\java ).
To install on a Windows Domino Server, complete the following steps:
Unzip the SOAPConnect for LotusScript package in the directory C:\SOAPConnect.
Rename file XML4j.jar to XML4j.jar-hidden in both the Domino program directory (by default C:\Lotus\Domino ) and the Domino Java directory (by default C:\Lotus\Domino\Data\domino\java ).
Copy all files in directory C:\SOAPConnect\ProgramDir to your Domino program directory (by default C:\Lotus\Domino ) and also copy them to the Domino Java directory (by default C:\Lotus\Domino\Data\domino\java ).
Copy all files in directory C:\SOAPConnect\DataDir to your Domino data directory (by default C:\Lotus\Domino\data ).
Understanding SOAPConnect for LotusScript
As you saw during the installation process, SOAPConnect for LotusScript consist of several Java libraries and Domino databases. Although Java technology is used underneath the covers, SOAPConnect allows developers to use LotusScript to create, send, and manipulate SOAP messages. To gain a high-level view of how SOAPConnect for LotusScript operates, the diagram below demonstrates the data flow and the transport protocol being used.
Figure 3. Data flow and transport protocol
As illustrated in Figure 3, whenever a user wants to view the price for specific book, a document is created in the SOAPCall Runner database. The SOAPCall agent in the SOAPCall Runner database uses Apache's SOAP library to create a SOAP message and send it across to XMethod's servers. XMethods is a virtual laboratory for developers to test various Web services from many different authors and organizations. In the sample database, XMethod's server acts a router between the request from SOAPConnect and Barnes & Noble's servers. After the request has been forwarded to Barnes & Noble's server and the book is located within their catalog, the book's price is sent back to the SOAPCall agent through XMethod's server. In turn, the SOAPCall agent returns the price back to the calling LotusScript agent within the book catalog database.
Invoking the Web service
Now that I've covered the basics of Web services and the behavior for your sample application, let's get started with reviewing how to invoke a Web service using the SOAPConnect for LotusScript package. In the sample database, the GetPrice LotusScript agent is called when the user clicks the Get Price button on the Book form. Amazingly enough, it only takes nine lines of code to invoke the Web service and return the data back to the agent. The code below illustrates the objects and methods necessary to get back a book's price.
1 %INCLUDE "SoapConnect"
2 Dim session As New NotesSession
3 Dim doc As NotesDocument
4 Dim myArgs(0) As Variant
5 Dim price As String
6 Set doc = session.DocumentContext
7 Dim bn As New SOAPClient(
"http://services.xmethods.com:80/soap/servlet/rpcrouter" )
8 myArgs( 0 ) = doc.BookNumber( 0 )
9 price = bn.invoke("urn:xmethods-BNPriceCheck", "getPrice", myArgs)
Let's step through this code snippet:
Before you can use the SOAPClient class, you need to signal to Domino the location of this resource. The Include directive on line 1 inserts the contents of SoapConnect.lss into the agent at compile time. The SoapConnect.lss was copied into your program directory during the installation of SOAPConnect.
Lines 2 through 6 set up variables you'll use during the execution of the agent.
Here's where it gets interesting. On line 7 you create a new SOAPClient with the location of the service endpoint. This example uses a service endpoint of XMethods. More information about XMethods is available at the end of the article.
Before you can invoke the Web service, you need to get the ISBN number of the book in question.
Line 9 invokes the Web service passing the namespace, method, and argument. The namespace variable corresponds to the service that will be loaded, in this case the xmethods-BNPriceCheck service. The myArgs variable contains the ISBN number for the book.
Figure 4 illustrates the GetPrice agent within Domino Designer 6.
Figure 4. The GetPrice agent
Summary
Lotus has made a commitment to embrace Web services as a way to utilize and extend Notes and Domino's collaborative features. With packages like SOAPConnect for LotusScript, it's exciting to explore how Domino can consume Web services using native tools and procedures. The sample database provides a framework that can be used to create your own databases to invoke Web services. Throughout this article the following topics were presented:
Introduction to the core technologies that make up Web services.
Coverage of the steps involved in installing SOAPConnect for LotusScript.
Exploration of how to use SOAPConnect for LotusScript within the context of a sample application.
Resources
Download Lotus Domino Designer 6 and Lotus Domino Server 6 trial versions.
Download the SOAPConnect for LotusScript package.
Download the companion Domino database that was demonstrated throughout this article.
The Apache SOAP project provides a Java SOAP implementation that is used within SOAPConnect for LotusScript.
Find out more about XMethods virtual laboratory for developers to list and test out available Web services.
Find out more about Building Web services with Domino 6.
Learn how to Turn your Lotus applications into Web services.
Page 1 of 1
Jeff Gunther is the General Manager and founder of Intalgent Technologies, an emerging provider of software products and solutions utilizing the Lotus Notes/Domino and Java 2 Enterprise Edition platforms. Jeff Gunther has been a part of the Internet industry since its early, "pre-Mosaic" days. He has professional experience in all aspects of the software life cycle including specific software development expertise with Lotus Notes/Domino, Java/J2EE technology, DHTML, XML/XSLT, database design, and handheld devices. You can contact him at jeff.gunther@intalgent.com.
