Consuming an External Web Service with Domino 6

原创 2004年07月13日 10:18:00

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.

Figure 1. The All Book view

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:

  1. Unzip the SOAPConnect for LotusScript package in the directory C:/SOAPConnect.
  2. Rename file XML4j.jar that is installed in the Notes program directory (by default C:/Lotus/Notes/XML4j.jar ) to XML4j.jar-hidden.
  3. Copy all files in directory C:/SOAPConnect/ProgramDir to your Notes program directory (by default C:/Lotus/Notes ).
  4. Copy all files in directory C:/SOAPConnect/DataDir to your Notes data directory (by default C:/Lotus/Notes/data ).
  5. 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:

  1. Unzip the SOAPConnect for LotusScript package in the directory C:/SOAPConnect.
  2. 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 ).
  3. 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 ).
  4. 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( "" ) 8 myArgs( 0 ) = doc.BookNumber( 0 ) 9 price = bn.invoke("urn:xmethods-BNPriceCheck", "getPrice", myArgs)

Let's step through this code snippet:

  1. 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.
  2. Lines 2 through 6 set up variables you'll use during the execution of the agent.
  3. 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.
  4. Before you can invoke the Web service, you need to get the ISBN number of the book in question.
  5. 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

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.


SpringBoot之Consuming a RESTful Web Service

  • xuanfengling
  • xuanfengling
  • 2016年06月13日 14:06
  • 880

Spring Boot 之 Consuming a RESTful Web Service

Consuming a RESTful Web Service .顾名思义,作为消费者,处理 RESTful Web Service返回的数据。 下载demo : git clone htt...
  • luosai19910103
  • luosai19910103
  • 2016年10月22日 23:13
  • 303

Consuming a RESTful Web Service

This guide walks you through the process of creating an application that consumes a RESTful web serv...
  • u013059432
  • u013059432
  • 2017年07月03日 10:43
  • 200


/** * Title: MailRedirectServlet * Description: 登录Domino服务器后直接打开用户的邮件! * 前提Domino配置成支持servelt, * 打开N...
  • YuLimin
  • YuLimin
  • 2003年08月13日 10:27
  • 5494


was与domino需要共享一个用户注册表,domino不支持自定义的用户注册表一。domino方面    配置并启动Lotus Domino的LDAP服务配置并启动Lotus Domino的LDAP...
  • fastrunner2003
  • fastrunner2003
  • 2006年08月31日 11:20
  • 1715

domino 视图 bs 漂亮显示(domino easyui)

在bs开发当中,经常会为怎样漂亮的视图而苦恼,上次我上传资源的内容里有入门(地址如下),今天上传个漂亮的界面以表示可以自己做,大家可以自己思考怎样做,只要你会了ajax,json就可以了 http:/...
  • weijia3624
  • weijia3624
  • 2015年02月05日 22:17
  • 1618

转一篇文章,归纳总结的不错,共同学习:《Domino Web 开发规则》

转自:     Domino Web开发规则   Domino Web开发规则之一:Notes...
  • CrazyNotes
  • CrazyNotes
  • 2012年11月15日 11:34
  • 1153

81. Domino视图Web展现技术胪列

  • starrow
  • starrow
  • 2014年10月15日 17:14
  • 5274


今天一朋友问,怎么判断用户是否已经在web端登录了。 可以在domino端控制台输入以下方式来获取: show inetusers -xml>保存XML的路径,然后解析xml...
  • Gavid0124
  • Gavid0124
  • 2015年01月13日 11:30
  • 1013

Consuming a RESTful Web Service with jQuery

GETTING STARTED Consuming a RESTful Web Service with jQuery This guide walks you through wri...
  • tmpbook
  • tmpbook
  • 2015年03月23日 16:02
  • 456
您举报文章:Consuming an External Web Service with Domino 6