Creating Web Services in Lotus Domino and Consuming them

Creating Web Services in Lotus Domino and Consuming them in SAP Portal Applications

SAP DEVELOPER NETWORK | sdn.sap.com BUSINESS PROCESS EXPERT COMMUNITY | bpx.sap.com

© 2006 SAP AG


Applies to: SAP Netweaver (NW04 and upwards) and Lotus Domino (7.0 and upwards)

Summary This article describes how to create a simple web service in Lotus Domino 7.0 and to create a simple Portal (Servlet) Application in SAP Netweaver Developer Studio that can make use of this web service. Also explained is how to expand this to business applications running on SAP Enterprise Portal. Author(s): Kalyanaraman B Krishnan Company: SAP Created on: 12 September 2006

Author Bio Kalyan is an IBM Certified Lotus Specialist, SAP Certified Technology Consultant for Enterprise Portal, Sun Certified Java Professional and IBM certified DB2 DBA and has been working for SAP for close to 3 years prior to which he was working for IBM (Lotus) for close to 4 years. The Co-inventor of 9 US patent pending inventions related to Groupware Collaboration, he has been involved in various groupware integration projects in SAP and is currently involved in Duet (formerly Mendocino).


SAP DEVELOPER NETWORK | sdn.sap.com BUSINESS PROCESS EXPERT COMMUNITY | bpx.sap.com © 2006 SAP AG 2

Table of Contents Applies to: ........................................................................................................................................ 1 Summary.......................................................................................................................................... 1 Author Bio ........................................................................................................................................ 1 Overview.......................................................................................................................................... 3 Advantages of an Enterprise SOA based Approach ....................................................................... 4 The Big Picture ................................................................................................................................ 5 Creating a Web Service in Domino ................................................................................................. 6

The new Web Service design element ........................................................................................ 6 Coding the new Web Service....................................................................................................... 7 Setting Web Service Properties ................................................................................................... 7 Accessing the Web Service ......................................................................................................... 9

Consuming the Web service using SAP Netweaver developer Studio ......................................... 10 Creating a Deployable Proxy for the web service...................................................................... 10 Creating a Servlet to invoke the web service through the proxy ............................................... 13 Setting the Servlet Project Properties ........................................................................................ 15

Conclusion ..................................................................................................................................... 19 Related Content............................................................................................................................. 20 Copyright........................................................................................................................................ 21



Overview With most organizations and enterprises moving towards Enterprise Service Oriented Architecture, it’s important to look beyond the jargon into what it means for developers and implementers and what exactly are the facilities provided by the various software products and solutions to enable Enterprise SOA based integration. To this purpose, this article explores the possibilities provided by Lotus Domino to create and expose web services and the possibilities provided by the SAP Netweaver Developer Studio to easy create and deploy web applications that can take advantage of Lotus Domino’s web services.



Advantages of an Enterprise SOA based Approach

• By Using Web services, SAP Netweaver Developers need not know Domino Native API

• In many situations the SAP Netweaver developers do not have to worry about the Domino landscape related complexities

• SAP Netweaver developers do not need to import or re-distribute Lotus Notes related jars (such as NCSO.jar or Notes.jar needed for other integration applications)

• Lotus Domino Developers can enable Web Services in any Domino application without worrying about which client is going to consume them

• Lotus Domino Administrators do not need to open the DIIOP port on the Domino Server (which is used for some of the current integration applications) which is considered to be slow and a potential security loophole*.

• Easy enablement of Business Process Integration using Integration applications such as SAP XI (Exchange Infrastructure) that has inbuilt support for web services

• No additional deployments on the Domino Server required. Since web services are an extension of already existing Domino Applications (.nsf) there is no need to deploy additional files on the server (unlike a servlet for example where you may need to deploy additional jar files)

• Profiling of web services is supported by Domino. You can track the number of calls made to a web service, which methods were invoked and what were the elapsed times.

• An SOA approach is more object oriented encapsulating underlying complexities of network communication which allows developers to focus more on business logic and enabling more complex enterprise applications to be developed

*In the guide for Securing Domino applications, IBM provides the advice that “Be aware that enabling the DIIOP server task in combination with allowing for server browsing may permit a malicious attack on your Domino server to occur.”



The Big Picture

Domino Server

Lotus Notes Application (.nsf) with Web ServiceDesign Element

SAP Ticket Verifier forSingle Sign On

Domino HTTP Server Task

SAP J2EE Engine

SAP J2EE/WebdynproApplication

Web Service Request with MYSAPSSO2 SSO Cookie

Web Service Request

MYSAPSSO2Cookie

AuthenticatedDomino User name

Web Service

Response

Web Service Response

The figure explains how an SAP Netweaver J2EE Application communicates with a web service in Lotus Domino. The application sends a web service request in the form of SOAP over HTTP which can also contain the encrypted MYSAPSSO2 cookie generated by the SAP J2EE Engine to enable single sign on. When this request is received by the Domino HTTP service, the listening SAP Ticket verifier decrypts the MYSAPSSO2 Cookie and identifies the Domino username to be authenticated. After the user has been authenticated the web service request reaches the Domino Application with the exposed web service (which is nothing but an .nsf file containing the web service design element). The request is then processed and the response is sent back to the requesting application using the same SOAP over HTTP.



Creating a Web Service in Domino Web services have been introduced in Lotus Domino from version 7.0 onwards. For earlier versions of Domino you had to download a web service toolkit from the Lotus website and install and configure various jar files and had to worry about the complex details of XML and SOAP but from 7.0 onwards many of the complexities are handled for you. The examples in this article assume version 7.0 for Lotus Domino. This article also assumes a basic awareness of Lotus Notes development including usage of Lotus Domino Designer and Lotus Script and a basic understanding of web service terminology (you can also look into Lotus Domino designer under web services->terminology).

The new Web Service design element Launch Domino Designer and create a new blank database (File->Database->New or CTRL+N) or open an existing database (File->Database->Open or CTRL+O). In the design view you will see that a new design element has been added to a Lotus Notes database called “Web Services”. Just click on “New Web Service” and you are on your way!

Note: To be able to run web services first ensure that in Domino Administrator, server document->Security tab-> Programmability Restrictions fields has the name of the person(s) who signs the web services such as the administrator user and also the server. By default these fields are blank allowing none.



Coding the new Web Service To create a new web service all you have to do is code a class within this web service design element and all the methods of the class automatically get exposed as web service methods. You can code this class in either Lotus Script or Java. If you do not want a particular method to be exposed just make that a Private Method by adding the “Private” qualifier before the function. For our example, we will create a very simple Lotus Script Class with only one method to add two numbers and return the result.

Class Math

Function add(A As Integer, B As Integer) As Integer

add = a+b

End Function

End Class

Setting Web Service Properties The full documentation for setting the properties is available in the Domino Designer Documentation so we’ll just focus on the most important parts. Right click on the coding pane and click Web service Properties to bring up the properties dialog. First we need to set the name of the Web Service Design element (and we call it Math) and we also need to specify which class is to be exposed as a web service and in our case the class “Math” that we coded in the previous step is the one to be exposed.



In the next tab we specify that we want the web service runs with the effective user name of the user invoking the Web service by checking “Run as web user”. For our simple Math example we don’t need to run any restricted operations.

The Final Advanced tab allows us to fine tune the Soap Message parameters to suit our needs. For our current example, the following settings will do. Readers are encouraged to read the Lotus Domino Documentation for the full range of possibilities.



Accessing the Web Service The web service that we created will have its definition called the WSDL available in the URL

http://servername<:port>/databasename.nsf/webservicename?WSDL

In our example this translates into http://localhost/test.nsf/Math?WSDL The web service itself is available in the URL

http://servername<:port>/databasename.nsf/webservicename?OpenWebService

In our example this translates into http://localhost/test.nsf/Math?OpenWebService



Consuming the Web service using SAP Netweaver developer Studio In our example we will create a simple servlet that will accept two numbers and invoke the web service we created above to add them and display the result in a browser window. A basic knowledge of using SAP Netweaver Developer Studio to be able to create and deploy a basic servlet in the SAP J2EE Engine using SAP Netweaver developer Studio is assumed to allow us to focus on the portion where we consume the web service. For further reading as to how to create a servlet and deploy it using the SAP Netweaver Developer Studio, please refer the online help Help->SAP Web AS Documentation->SAP Web J2EE Applications.

Creating a Deployable Proxy for the web service A web service proxy allows you to call a remote function as any other normal method call and removes the complexities of SOAP and XML and HTTP connectivity from you. So we will now create a deployable proxy project for the domino web service we created. Launch SAP Netweaver Developer Studio and switch to the “Web Service Perspective and create a new Deployable Proxy project. Let’s call this project as “Domino Web Service Proxy”.

Once the project is created, Right Click and Create a new Client Proxy definition



Provide the package details and choose the WSDL from a URL or local file.

I would recommend that you access the WSDL URL given earlier under “Accessing the web service” (http://servername<:port>/databasename.nsf/webservicename?WSDL) in a browser first and saving it locally and then using the local file for proxy generation to avoid certain authentication issues between SAP Netweaver developer studio and Domino server. In our example, we will use basic authentication to authenticate to the web service, in production scenarios, it’s recommended to use the SAP Logon Ticket for Single Sign on with Domino. To set the security options, open the logical ports in our proxy project and click on Math and click on the security tab on the window that opens in the right pane.



Once the proxy has been generated, right click on the project, build the ear and deploy into the SAP J2EE Engine.

Once successfully deployed, you will be able to see that a new Destination has been created for our web service in the SAP J2EE Engine. You can see this in Visual Administrator (Server->Services->Destinations).



Enter the Lotus Domino user’s name and password for connecting to the domino web service here and then click Save and Test. If successful, you should get a message that HTTP 200 was successful. In case of problems check network connectivity and username/password. Of course in production situations you may want to choose “Logon Ticket” instead of Basic Authentication here. Still in Visual Administrator, you will be able to see the JNDI name for this newly deployed application under Server->Services->JNDI Registry.

That’s all there is to it! Now your Deployable Proxy is ready for use by any SAP J2EE Application!

Creating a Servlet to invoke the web service through the proxy Based on the SAP Netweaver Developer Studio documentation, it’s a breeze to create the servlet (create a web module project and right click and create a servlet). You can use this code for the servlet. package com.sap.xapps; import java.io.IOException;



import java.io.PrintWriter; import javax.naming.InitialContext; import javax.servlet.ServletException; import javax.servlet.http.HttpServlet; import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import com.sap.lotus.MathService; public class SAPServlet extends HttpServlet { protected void doGet( HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { PrintWriter pw = response.getWriter(); try { short a=Short.parseShort(request.getParameter("a")); short b=Short.parseShort(request.getParameter("b")); InitialContext in = new InitialContext(); MathService mathService = (MathService)in.lookup("wsclients/proxies/sap.com/Domino_Web_Service_Proxy/com.sap.lotus.MathProxy"); com.sap.lotus.Math mathws = mathService.getLogicalPort(); pw.write("Result = " + mathws.ADD(a, b)); } catch(Exception e) { pw.write(e.toString()); e.printStackTrace(); } } }

This code simply gets two short variables from the request, performs an initial lookup for the Deployable Proxy we created and than call the web service’s add method.



Setting the Servlet Project Properties Once the servlet has been created, we need to make it reference the Deployable proxy project that we created for build time dependencies.



Then we also need to make sure that we include a hard reference to the project for deploy time dependencies.



If the build asks for a missing jax rpc jar file, you will find it under <install drive>/usr/sap/<sid>/ <instance>/j2ee/j2eeclient/jaxrpc-api.jar which you can add under external jars. You may also be interested in creating a servlet mapping to determine the URL of your servlet in the SAP J2EE Engine. Then create an Enterprise Archive project (ear) and add this servlet project to the EAR Project.



Warning: There is a quirk in the SAP Netweaver developer studio where projects with spaces in them give problems. So you may have to go to the EAR Project’s application-j2ee-engine.xml and click on the source tab and manually add underscore _ to replace the spaces. Below is a sample

<?xml version="1.0" encoding="UTF-8"?>

<!DOCTYPE application-j2ee-engine SYSTEM "application-j2ee-engine.dtd">

<application-j2ee-engine>

<reference

reference-type="hard">

<reference-target

provider-name="sap.com"

target-type="application">Domino_Web_Service_Proxy</reference-target>

</reference>

<provider-name>sap.com</provider-name>

<fail-over-enable

mode="disable"/>

</application-j2ee-engine>

Build the War and EAR files and Deploy the EAR file into the SAP J2EE Engine. That’s all there is to it! You have now successfully created an application on the SAP J2EE Engine to consume a Domino Web service. Invoke the servlet (based on your servlet mapping with this URL.

http://sapj2eeenginename:<port>/<servletname>/URLPattern?a=<value>&b=<value>

In our example this evaluates to http://localhost:50000/SAPServlet/SAPServlet?a=2&b=3. If all was successful you will get the response on the browser



Conclusion In this article we explored how to create a web service in Lotus Domino and consume it in a J2EE application running on the SAP J2EE Engine. In a real life production environment a likely application would be to create web service methods for the objects in a Lotus Domino Database application and invoke these methods remotely from an SAP Portal Application for integrating Business Objects and Business Scenarios from heterogeneous environments. The reader is also encouraged to look into the various single sign on options provided by SAP and also may explore further how to use SAP XI for modeling various integration scenarios.



Related Content IBM Lotus Interoperability Single Sign on between SAP Enterprise Portal and Lotus Domino Securing Domino Applications



Copyright © Copyright 2006 SAP AG. All rights reserved. No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP AG. The information contained herein may be changed without prior notice. Some software products marketed by SAP AG and its distributors contain proprietary software components of other software vendors. Microsoft, Windows, Outlook, and PowerPoint are registered trademarks of Microsoft Corporation. IBM, DB2, DB2 Universal Database, OS/2, Parallel Sysplex, MVS/ESA, AIX, S/390, AS/400, OS/390, OS/400, iSeries, pSeries, xSeries, zSeries, z/OS, AFP, Intelligent Miner, WebSphere, Netfinity, Lotus, Tivoli, Informix, i5/OS, POWER, POWER5, OpenPower and PowerPC are trademarks or registered trademarks of IBM Corporation. Adobe, the Adobe logo, Acrobat, PostScript, and Reader are either trademarks or registered trademarks of Adobe Systems Incorporated in the United States and/or other countries. Oracle is a registered trademark of Oracle Corporation. UNIX, X/Open, OSF/1, and Motif are registered trademarks of the Open Group. Citrix, ICA, Program Neighborhood, MetaFrame, WinFrame, VideoFrame, and MultiWin are trademarks or registered trademarks of Citrix Systems, Inc. HTML, XML, XHTML and W3C are trademarks or registered trademarks of W3C®, World Wide Web Consortium, Massachusetts Institute of Technology. Java is a registered trademark of Sun Microsystems, Inc. JavaScript is a registered trademark of Sun Microsystems, Inc., used under license for technology invented and implemented by Netscape. MaxDB is a trademark of MySQL AB, Sweden. SAP, R/3, mySAP, mySAP.com, xApps, xApp, SAP NetWeaver, and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP AG in Germany and in several other countries all over the world. All other product and service names mentioned are the trademarks of their respective companies. Data contained in this document serves informational purposes only. National product specifications may vary. These materials are subject to change without notice. These materials are provided by SAP AG and its affiliated companies ("SAP Group") for informational purposes only, without representation or warranty of any kind, and SAP Group shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP Group products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty. These materials are provided “as is” without a warranty of any kind, either express or implied, including but not limited to, the implied warranties of merchantability, fitness for a particular purpose, or non-infringement. SAP shall not be liable for damages of any kind including without limitation direct, special, indirect, or consequential damages that may result from the use of these materials. SAP does not warrant the accuracy or completeness of the information, text, graphics, links or other items contained within these materials. SAP has no control over the information that you may access through the use of hot links contained in these materials and does not endorse your use of third party web pages nor provide any warranty whatsoever relating to third party web pages. Any software coding and/or code lines/strings (“Code”) included in this documentation are only examples and are not intended to be used in a productive system environment. The Code is only intended better explain and visualize the syntax and phrasing rules of certain coding. SAP does not warrant the correctness and completeness of the Code given herein, and SAP shall not be liable for errors or damages caused by the usage of the Code, except if such damages were caused by SAP intentionally or grossly negligent.

Documents

Creating Web Services in Lotus Domino and Consuming them