ibm websphere adapter for lotus domino 7.5.0 · websphere adapter for lotus domino is a j2ee...

IBM WebSphere Adapter for Lotus Domino 7.5.0.0

Quick Start Scenario

Note: Before using this information and the product it supports, read the information in "Notices" on page 108.

This edition applies to version 7, release 0, and modification 5 of IBM WebSphere Adapter for Lotus Domino and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright International Business Machines Corporation 2011. US Government Users Re-stricted Rights – Use, duplication, or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

1

I

Table of contents

Chapter 1 Introduction................................................................... 1

1.1 Learning Objectives ........................................................................................................... 1

1.2 Audience.............................................................................................................................. 1

1.3 Software prerequisites ....................................................................................................... 1

1.4 Scenarios in brief................................................................................................................ 1 1.4.1 Outbound processing of documents.............................................................................. 2 1.4.2 Outbound processing of documents with additional information for the selected items 2 1.4.3 Outbound processing of documents with RichText data............................................... 2 1.4.4 Inbound processing of documents ................................................................................ 2 1.4.5 Inbound processing of documents with RichText data.................................................. 2

Chapter 2 Preparing to run through the tutorial......................... III

2.1 Extracting sample files...................................................................................................... III

2.2 Configure the Domino server ........................................................................................... IV

2.3 Create a database for use in scenarios............................................................................ V

2.4 Deploy SampleDatabase on the Domino server........................................................... VIII

2.5 Create a Module in IBM Integration Developer ............................................................... IX Chapter 3 Tutorial 1: Outbound processing of documents.......XI

3.1 User story ........................................................................................................................... XI

3.2 Configuration prerequisites.............................................................................................. XI

3.3 Check the Form used in this tutorial ............................................................................... XI

3.4 Create an outbound interface into a Module using Lotus Domino adapter ................ XI

3.5 Deploy the Module to IBM Process Server ................................................................. XXV

3.6 Test Operations .......................................................................................................... XXVIII 3.6.1 Test Create operation.............................................................................................. XXIX 3.6.2 Test Exists operation ..............................................................................................XXXV 3.6.3 Test Update operation..........................................................................................XXXVII 3.6.4 Test Retrieve operation ............................................................................................... XL 3.6.5 Test RetrieveAll operation ........................................................................................... XL 3.6.6 Test Delete operation ................................................................................................ XLII

Chapter 4 Tutorial 2: Outbound processing of documents with additional information for the selected items...................XLIII

4.1 User story .......................................................................................................................XLIII

4.2 Configuration prerequisites..........................................................................................XLIII

4.3 Check the Form using in this tutorial ......................................................................... XLIV

4.4 Create an outbound interface into a Module using Lotus Domino adapter ........... XLIV

4.5 Deploy the Module to IBM Process Server .............................................................. XLVIII

4.6 Test operations ............................................................................................................. XLIX 4.6.1 Test Create operation...............................................................................................XLIX 4.6.2 Test Retrieve operation ................................................................................................. L 4.6.3 Test RetrieveAll operation ........................................................................................... LII 4.6.4 Test Update operation................................................................................................ LIII 4.6.5 Test Exists and Delete operation ............................................................................... LIII Chapter 5 Tutorial 3: Outbound Processing of documents

with RichText data.........................................................................LIV

5.1 User story .........................................................................................................................LIV

5.2 Configuration prerequisites............................................................................................LIV

5.3 Check the Form used in this tutorial .............................................................................LIV

5.4 Create an outbound interface into a Module using Lotus Domino adapter ..............LIV

5.5 Deploy the Module to IBM Process Server ...................................................................LVI

5.6 Test operations ...............................................................................................................LVII 5.6.1 Test Create operation................................................................................................ LVII 5.6.2 Test Retrieve operation ............................................................................................ LVIII 5.6.3 Test RetrieveAll operation .......................................................................................... LIX 5.6.4 Test Update operation................................................................................................. LX 5.6.5 Test Exists and Delete operation ................................................................................ LX

Chapter 6 Tutorial 4: Inbound processing of documents.........LX

6.1 User story ..........................................................................................................................LX

6.2 Configuration prerequisites............................................................................................LXI

6.3 Preparation for the Domino server ................................................................................LXI 6.3.1 Preparation on Windows system................................................................................ LXI 6.3.2 Preparation on the AIX server ................................................................................... LXII

6.4 Check the Form used in this tutorial ...........................................................................LXIII

II

6.5 Create an inbound interface into a Module using the Lotus Domino adapter ........LXIII

6.6 Deploy the Module to IBM Process Server .............................................................. LXVIII

6.7 Test Interface .............................................................................................................. LXVIII 6.7.1 Prerequisites...........................................................................................................LXVIII 6.7.2 Test Create operation.............................................................................................LXVIII 6.7.3 Test Update operation..............................................................................................LXIX 6.7.4 Test Delete operation ................................................................................................LXX

Chapter 7 Tutorial 5: Inbound processing of documents with RichText data LXXI

7.1 User story ...................................................................................................................... LXXI

7.2 Configuration prerequisites......................................................................................... LXXI

7.3 Check the Form used in this tutorial ......................................................................... LXXII

7.4 Create an inbound interface into a Module using the Lotus Domino adapter ...... LXXII

7.5 Deploy the Module to IBM Process Server .............................................................. LXXVI

7.6 Test Interface .............................................................................................................. LXXVI 7.6.1 Prerequisites.......................................................................................................... LXXVI 7.6.2 Test Create operation........................................................................................... LXXVII 7.6.3 Test Update operation........................................................................................... LXXIX 7.6.4 Test Delete operation ............................................................................................. LXXX

Chapter 8 Troubleshooting ...................................................LXXXI

8.1 Allow browsing of the database through HTTP....................................................... LXXXI 8.1.1 Symptom ............................................................................................................... LXXXI 8.1.2 Cause .................................................................................................................... LXXXI 8.1.3 Resolution............................................................................................................. LXXXII

8.2 Configure Domino server’s Internet host name ..................................................... LXXXII 8.2.1 Symptom .............................................................................................................. LXXXII 8.2.2 Cause ................................................................................................................... LXXXII 8.2.3 Resolution............................................................................................................. LXXXII

8.3 Idle session timeout .................................................................................................. LXXXII 8.3.1 Symptom .............................................................................................................. LXXXII 8.3.2 Cause .................................................................................................................. LXXXIII 8.3.3 Resolution............................................................................................................ LXXXIII

Αππενδιξ Α Create a database, form, and field in the Domino server LXXXIII

1 Create a database......................................................................................................... LXXXIII

2 Create a form in the database.....................................................................................LXXXVI

III

3 Create a field in the Form ..........................................................................................LXXXVIII Αππενδιξ Β Verify document through Lotus Notes................... XC

1 Verify the created document .............................................................................................. XC

2 Check the Universal ID .................................................................................................... XCIII Αππενδιξ Χ Check the form created in section 2.3 .................XCV

1 Check the form employee.................................................................................................XCV

2 Check the form EmployeeWithRichText .........................................................................XCV Αππενδιξ Δ Import the sample to your workspace.................XCVI Notices ............................................................................................CII

Table of figures

Figure 1 Samples directory ............................................................. 3 Figure 2 The pi directory.................................................................. 3 Figure 3 Sample database ............................................................... 3 Figure 4. ................................................................Start DIIOP server 4 Figure 5. ....................................... Select Current Server Document 5 Figure 6. .......... Select to allow HTTP clients to browse databases 5 Figure 7. ................................................... Create an employee form 6 Figure 8. ......................................... Structure of the employee form 7 Figure 9. .................................................... Sample database design 8 Figure 10. ................................................................ Create a module 9 Figure 11. ............................................Enter a name for the module 10 Figure 12. .................Module project displayed in the project view 10 Figure 13. ......................................................Select external service 12 Figure 14. ...................................Select the service type or registry 13 Figure 15. .................................... Select the Lotus Domino adapter 14

IV

Figure 16. ............................................................... Import a RAR file 15 Figure 17. ....................................... Select the processing direction 16 Figure 18. .........................................Specify connection properties 17 Figure 19. .............................Find objects in the enterprise system 18 Figure 20. .................................................... Select query properties 19 Figure 21.Select discovered objects to move to the selected area 20 Figure 22. .........Move the discovered objects to the selected area 21 Figure 23. .......................................... Specify composite properties 22 Figure 24. ............................................ Choose security credentials 23 Figure 25. .....................................Specify the module and its name 24 Figure 26. .......Displaying the sample project in the project's area 25 Figure 27. ...................................... Select add and remove projects 26 Figure 28. Add the sample project for configuration on the server 27 Figure 29. ................ Sample project added to configured projects 28 Figure 30. ....................................................Start the Domino server 29 Figure 31. .................................................................Test the module 30 Figure 32. ..... Specify detailed properties for the create operation 31 Figure 33. .........................Specify the data for the business object 32 Figure 34. ..........................................................Select add elements 33 Figure 35. .......................... Specify the number of elements to add 33 Figure 36. ...........................................Click continue to run the test 33 Figure 37. .......... Select to deploy on the IBM Process Server v7.5 34 Figure 38. ................................................... Check the server output 35 Figure 39. ........................................ Specify the detailed properties 35 Figure 40. ...........................Copy the universal ID of the document 36 Figure 41. ..................................................Displays the universal ID 37 Figure 42. ...........................................Check if the document exists 37 Figure 43. .......................Enter new values for the business object 38

V

Figure 44. ............................................... Check the business object 39 Figure 45. ..............................................Verify the update operation 39 Figure 46. ................................Check the returned business object 40 Figure 47. .............................Unset the double and the date values 41 Figure 48. ...................... Enter value in the employee number field 41 Figure 49. .......................................Check the business object data 42 Figure 50. ................................Check the returned business object 43 Figure 51. ............................................... Select the Domino adapter 46 Figure 52.Select to set additional configurations during object selection 47Figure 53. ................Select configuration properties for employee 48 Figure 54. ....................... Displaying the business object structure 49 Figure 55. .............................................. Specify detailed properties 50 Figure 56. .......................Verify the database of the Domino server 51 Figure 57. ...................................... Check the data in the document 51 Figure 58. ........................................ Specify the detailed properties 52 Figure 59. ................................Check the returned business object 53 Figure 60.Update the module using new values along with existing values 54Figure 61. ......Business object structure of the rich text data type 57 Figure 62.Business object structure of rich text data type with attachment 57Figure 63. ..............................Attachments to test create operation 58 Figure 64. .......................Verify the database in the Domino server 59 Figure 65. ............................................... Check the business object 60 Figure 66. ................Required directories on the Windows system 63 Figure 67.Select the configuration view to check the WALD inbound event tableFigure 68. ......................................................Configure the log level 64 Figure 69. ........................................ Select the inbound processing 66 Figure 70.Enter the value in the adapter instance for event filtering field 67Figure 71. .. Check the assembly diagram for the inbound sample 67

VI

Figure 72. .............................................. Select the Java component 68 Figure 73. .......................................................................Add the wire 68 Figure 74. ................................... Confirm the component selection 68 Figure 75. ........................... Wire the interface with the component 70 Figure 76. .................................................Select the employee form 71 Figure 77. ..........................Enter new values in the employee form 71 Figure 78. ....Check if the new employee is added in the database 71 Figure 79. .............Update the employee salary details in the form 72 Figure 80. ...........................Check the update event in the console 72 Figure 81. .......................Check if the delete event was successful 73 Figure 82.Move the employee with rich text form to the selected objects areaFigure 83.Displaying the domino inbound rich text interface in the assembly diaFigure 84. ..............Connect the interface to the target component 79 Figure 85. .......................Files as attachments to test the interface 80 Figure 86. ................................................Select files for attachment 81 Figure 87. ................................. Attachments to the employee form 82 Figure 88. ................................... Console view for the create event 82 Figure 89. ....................................................Update the attachments 83 Figure 90. ....................................Console view of the update event 83 Figure 91. .....................................Console view of the delete event 84 Figure 92. ............................... Create a new application (database) 88 Figure 93. ......................................... Configure the new application 89 Figure 94. ............................................... Sample database contents 90 Figure 95. ............................................................ Create a new Form 91 Figure 96. ................................................Enter a name for the Form 91 Figure 97. ................................................. Create a field in the Form 92 Figure 98. ............................................................. Enter a field name 92 Figure 99. ...........................................................Select the field type 93

VII

Figure 100. ...................................... Select to allow multiple values 93 Figure 101. .................................................. Select a security option 94 Figure 102. ...........................................................Open a workspace 95 Figure 103. ..........................Open an application in the workspace 95 Figure 104. ....Select the Domino server and the sample database 96 Figure 105. ...............................View the document in the database 96 Figure 106. ..................... Check the output of the create operation 96 Figure 107. ................ Open to configure the document properties 97 Figure 108. .............Click the Meta tab in the document properties 98 Figure 109. .......................Check the universal ID of the document 98 Figure 110. ...............................................Check the employee form 99 Figure 111. ..................................... Structure of the employee form 100 Figure 112. ................................................. Select the import option 101 Figure 113. ............................................. Select project interchange 102 Figure 114. ............................. Import project interchange contents 103 Figure 115. ................................ Build business integration project 104 Figure 116. .......................................Change connection properties 105

VIII

1

Chapter 1.........................................................Introduction

WebSphere Adapter for Lotus Domino is a J2EE component compliant with the JCA 1.5 specifi-cation. The adapter enables bidirectional connectivity to a database on the Lotus Domino server. This guide provides tutorial scenarios that demonstrate how the adapter performs outbound and inbound operations.

To gain practical knowledge in setting up and deploying the adapter, complete one or more of the tutorials. Everything you need to complete a tutorial is contained in the tutorial. Perform the pre-requisite tasks, before you attempt to complete the tutorials. Each tutorial takes less than an hour to complete.

1.1 Learning Objectives

After completing a tutorial, you should be able to perform the following tasks:

• Create an adapter project in IBM® Integration Developer • Discover services and associated business objects from the enterprise information sys-

tem (EIS) and make them part of the adapter project • Create a deployable module that you install on IBM Process Server or WebSphere En-

terprise Service Bus • Test the module and validate the results

1.2 Audience

These tutorials are for integration developers who design, assemble, test, and deploy busi-ness integration solutions.

1.3 Software prerequisites

To use these tutorials, you must have the following applications installed:

• IBM Integration Developer, version 7.5 • IBM Process Server or WebSphere Enterprise Service Bus, version 7.5

1.4 Scenarios in brief

There are five scenarios:

i. Outbound processing of documents

ii. Outbound processing of documents with additional information for the selected items

iii. Outbound Processing of documents with RichText data

iv. Inbound processing of documents

v. Inbound processing of documents with RichText data

1.4.1 Outbound processing of documents

This scenario shows you how to use Lotus Domino adapter to generate business ob-jects which can wrap the data in Domino server and interface that can operate these business objects. There are five supported operations: Create, Delete, Update, Re-trieve, and RetrieveAll. The data processed in this scenario is for documents without any additional information.

The scenario is shown in Chapter 3.

1.4.2 Outbound processing of documents with additional information for the selected items

This scenario shows you the outbound processing of data but with additional informa-tion. The business object data in this scenario is a document with additional informa-tion.


1.4.3 Outbound processing of documents with RichText data

This scenario shows you the outbound processing of data with rich text. The busi-ness object data in this scenario is a document with RichText data which has text and attachment content.


1.4.4 Inbound processing of documents

This scenario shows you how to use to use Lotus Domino adapter to generate an in-terface that can process inbound data. In inbound processing, the interface is in-voked when a create, update, or delete event takes place in the Domino server.


1.4.5 Inbound processing of documents with RichText data

This scenario shows you how to use to use Lotus Domino adapter to generate an in-terface that can process inbound business object data which is a document with RichText data.


2

III

Chapter 2 Preparing to run through the tuto-rial

Before working on the tutorials (Chapter 3 to Chapter 7), complete the steps described in this chapter to prepare the adapter for use in the tutorials.

2.1 Extracting sample files

Extract the sample archive file.

1. Extract the archive file samples.zip to a directory, for example C:\samples.

2. The files and folders shown in the following figure describe the “samples” directory contents. There are two directories and one PDF file. The IBM WebSphere Adapter for Lotus Domino QSS.pdf file contains the Domino adapter tutorial.

Figure 1. Samples directory

3. The directory pi contains the samples. You can import these samples using the Pro-ject Interchange.

Figure 2. The pi directory

4. The database directory contains the sample database.

Figure 3. Sample database

2.2 Configure the Domino server

To do the following steps you must be familiar with Lotus Domino and Lotus Notes (including Domino Designer and Domino Admin). Also make sure your Domino server is running. For detail information on any of the steps, please refer to Lotus Domino and Notes documenta-tion.

1. Start Domino Admin and log in using your admin ID.

2. To enable JAVA API to access Domino databases, ensure that the DIIOP protocols of Domino are in use.

a) Configure the Domino server to start DIIOP at startup

i. Add “DIIOP” into “ServerTasks” property of the “notes.ini” file.

ii. Restart the Domino server.

b) Start the DIIOP task after Domino server has been started through the Dom-ino Administrator

i. Click the Domain tab.

ii. Click the Server tab in the Domain tab.

iii. Click the Status tab in the Server tab.

iv. Click Server Tasks to make sure DIIOP Server task is started.

Figure 4. Start DIIOP server

3. To make Enterprise Metadata Discovery (EMD) function workable, you should allow HTTP clients to browse Domino databases.

a) In Domino Administrator, click the Configuration tab.

b) Click to expand the Server node in the left pane, and then click the Current Server Document.

IV

Figure 5. Select Current Server Document

c) Click the Internet Protocols tab. The HTTP tab is selected by default.

d) In the R5 Basics section, select Yes to allow HTTP clients to browse Dom-ino databases.

Figure 6. Select to allow HTTP clients to browse databases

2.3 Create a database for use in scenarios

In this section, you should create a database SampleDatabase and two forms: Employee and EmployeeWithRichText. Also, you should create a view name “All employees” that can show

V

the basic information of a document. Refer to Appendix A for how to create a database in the Domino server.

1. Create a form named Employee using the following fields.

Field Name Field Type Multi-Value Security Options EmployeeNumber Text False None EmployeeName Names False None Address Text True None DateOfJoining Date False None Salary Number False Editor access to use PreviousReviewDates Date True None PreviousRatings Number True None

2. The form should show similar structure as the following figure after it has been cre-ated.

Figure 7. Create an employee form

3. Create a form named EmployeeWithRichText using the following fields.

Field Name Field Type Multi-Value Security Options EmployeeNumber Text False None EmployeeName Names False None Address Text True None DateOfJoining Date False None Salary Number False Editor access to use PreviousReviewDates Date True None PreviousRatings Number True None Resume RichText None

4. After the form is created, it should look similar to the following figure.

VI

Figure 8. Structure of the employee form

5. Create a View named “All employees” using the following table.

Column Name Column Value Form Field-Form EmployeeNumber Field- EmployeeNumber EmployeeName Field- EmployeeName Address Field- Address DateOfJoining Field- DateOfJoining Salary Field- Salary PreviousReviewDates Field- PreviousReviewDates PreviousRatings Field- PreviousRatings

6. Select Formula for the view selection of All employees and type SELECT (form = "Employee") | (form = "EmployeeWithRichText").

7. After creating the two forms and the view, the database design should look similar to the following figure.

VII

Figure 9. Sample database design

2.4 Deploy SampleDatabase on the Domino server

Note: If you create the database “SampleDatabase.nsf” on your Domino server directly, you can skip this section. Otherwise (if the database is created on the local disk), continue with this section.

1. In section 2.3, you already created the database “SampleDatabase.nsf” which will in the following chapters. You can find the database file in your Lotus Notes directory, for example, “C:\Program Files\IBM\Lotus\Notes\Data\SampleDatabase.nsf”.

2. You can also get the database file in the archive file samples.zip. If you did not cre-ate a database correctly in section 2.3, you can extract the archive file and get the database file.

3. Copy the database file “SampleDatabase.nsf” to the Data directory of your Domino server installation directory. For example, “C:\Program Files\IBM\Lotus\Domino\Data”.

VIII

2.5 Create a Module in IBM Integration Developer

This section tells you how to create a Module for use in following chapters of the tutorials.

1. Switch to Business Integration perspective and click File > New > Module.

Figure 10. Create a module

2. In the New Module window, type the module’s name in Module Name field, for ex-ample SampleModule. Click Finish.

IX

Figure 11. Enter a name for the module

Check the newly created SampleModule module in the Project view as shown in the following figure.

Module project displayed in the project view

X

Chapter 3 Tutorial 1: Outbound processing of documents

3.1 User story

In this scenario, the user uses Lotus Domino to manage basic information of the company employees. The user has designed a form Employee with Lotus Domino Designer and the in-formation of an employee, for example, Alice M. Smith, is represented as a document in the form of Employee. The runtime, the user manages the employee information through WPS and each employee is represented as a business object. The user creates, retrieves, updates and deletes the employee information through outbound operations: Create, Retrieve, Up-date, Delete. The user tests whether an employee exists through outbound operation Exists. The user also lists all employees who’s EmployeeNumber match the user input pattern.

When user triggers an outbound operation, the adapter receives a request from the module, in the form of a business object, to perform an operation on a file on the Domino database. The adapter performs the requested operation and returns a business object, if applicable, that represents the result of the operation to the component.

This tutorial demonstrates how to import an outbound interface in a module using Lotus Dom-ino adapter and process data in Domino database using an interface. The data will be proc-essed without additional information, and it includes both single value and multiple values. The EmployeeName of an employee is represented as a Lotus Domino Text in this scenario.

3.2 Configuration prerequisites

Before starting this tutorial, perform the following tasks:

• Ensure that you have finished the tutorial in Chapter 2. • Ensure the Domino server is running

3.3 Check the Form used in this tutorial

To finish the tutorial in this chapter, you should have a database SampleDatabase and a form Employee in this database. Refer to section 1 of Appendix C to learn how to check the form.

3.4 Create an outbound interface into a Module using Lotus Domino adapter

1. Open the Business Integration Perspective in your IBM Integration Developer.

2. Create a new module named OutboundSampleBasic for this chapter.

XI

Right-click on the module OutboundSampleBasic which you created and select New > External Service.

Figure 12. Select external service

3. In Select the Service Type or Registry window, expand the Adapters node and se-lect Lotus Domino. Click Next.

XII

Figure 13. Select the service type or registry

4. In Select an Adapter window, Select IBM WebSphere Adapter for Lotus Domino, and click Next.

XIII

Figure 14. Select the Lotus Domino adapter

5. In Import a RAR File window, accept the default setting and click Next.

XIV

Figure 15. Impo

rt a RAR file

6. In Select the Processing Direction window, select Outbound for this chapter. Click Next.

XV

Figure 16. Select the processing direction

7. In the Discovery Configuration window, enter the Host name, DIIOP port number (63148 for default), User name and Password. Click Next.

XVI

Figure 17. Specify connection properties

8. In the Find Objects in the Enterprise System window, click Edit Query to specify the filter conditions.

XVII

Figure 18. Find objects in the enterprise system

9. In the Query Properties window, type sample* in Database field and employee in Form field. Click OK.

XVIII

Figure 19. Select query properties

10. Click Run Query, and then click SampleDatabase.nsf > Employee. Refer to Chap-ter 2 for more information on how to create the sample database.

XIX

Figure 20. Select discovered objects to move to the selected area

11. Click the arrow and to move the Employee form in the Selected objects area. Click Next.

XX

Figure 21. Move the discovered objects to the selected area

12. In the Specify Composite Properties window, accept the default settings and click Next.

XXI

Figure 22. Specify composite properties

13. In the Service Generation and Deployment Configuration window, enter the con-nection properties for runtime. Choose the second option for the security credential and type your User name and Password. You can also specify it later for each sin-gle interface. Click Next.

XXII

Figure 23. Choose security credentials

14. In the Specify Location Properties window, ensure that OutboundSampleBasic is entered in the Module field. Also, change the Name field to DominoOutbound-BasicItemInterface. Accept the defaults for other settings and click Finish.

XXIII

Figure 24. Specify the module and its name

After you complete these steps, IBM Integration Developer will create an Adapter project for you. The adapter will create an interface and several business object definitions (data types). Also, you will find a DominoOutboundBasicItemInterface in Assembly Diagram. Press Ctrl-S to save all of the created configurations.

XXIV

Figure 25. Displaying the sample project in the project's area

You may also import the sample directly to your workspace. Refer to Appendix D to learn how to import a sample to your workspace.

3.5 Deploy the Module to IBM Process Server

The result of the previous section is an SCA module that contains an EIS import. Install this SCA module in IBM Process Server V7.5 which enables you to test the module.

You can also import the sample to your workspace directly following the instructions in Ap-pendix D. The Tutorial1.zip is the interchange project file for this chapter’s sample.

1. Add the module you created earlier to the server using the server panel in IBM Inte-gration Developer. In the Servers tab, right-click the IBM Process Server 7.5, and se-lect Add and Remove Projects.

XXV

Figure 26. Select add and remove projects

2. In the Add and Remove Projects window, select OutboundSampleBasicApp and click Add to add the module to server.

XXVI

Figure 27. Add the sample project for configuration on the server

3. Click Finish.

XXVII

Figure 28. Sample project added to configured projects

3.6 Test Operations

You can now test the interface you created earlier. To test the module, ensure the server is started. You can right-click the IBM Process 7.5 server, and select Start in the Servers tab to start the server.

XXVIII

Figure 29. Start the Domino server

3.6.1 Test Create operation

1. Right-click the module and select Test > Test Module.

XXIX

Figure 30. Test the module

2. Ensure that you select the correct module, component, interface, and operation.

• Module: OutboundSampleBasic • Component: DominoOutboundBasicItemInterface • Interface: DominoOutboundBasicItemInterface • Operation: createSampleDatabaseEmployee

XXX

Figure 31. Specify detailed properties for the create operation

3. Populate the following values for input business objects as shown in the following screen capture. Specify the input data as shown in the following table.

Properties Name Properties Value EmployeeNumber E000001 EmployeeName Alice M. Smith

Address

NO.92; 1st Street; New York; USA

DateOfJoining 2001-12-01 Salary 100000

PreviousReviewDates 2002-03-01; 2003-03-01; 2004-03-01

PreviousRatings 2.8; 2.7; 2.9

XXXI

Figure 32. Specify the data for the business object

NOTE: To enter value into an array field, right-click on the field and select Add Elements. Then, type a number in Add Element window.

XXXII

Figure 33. Select add elements

Figure 34. Specify the number of elements to add

4. Click Continue to run the test.

Figure 35. Click continue to run the test

5. In the Deployment Location window, select IBM Process Server v7.5 and click Fin-ish.

XXXIII

Figure 36. Select to deploy on the IBM Process Server v7.5

6. After server processes the operation, you can check the output.

XXXIV

Figure 37. Check the server output

You can also verify the result of the operation through Lotus Notes client. Refer to sec-tion Appendix B for how to verify the result through Lotus Notes client.

3.6.2 Test Exists operation

1. Click the icon in the test client and select existsSampleDatabaseEmployee in the Operation field.

Figure 38. Specify the detailed properties

XXXV

2. Copy the Universal ID of the document you created earlier to the UniversalID field in the test client. You can find the value of the Universal ID from the returned business object of the Create operation.

Figure 39. Copy the universal ID of the document

XXXVI

Figure 40. Displays the universal ID

3. Click Continue and check the result. The success field of returned business object is true.

Figure 41. Check if the document exists

4. You can change the UniversalID field and run the test again. The return value of Success field should be false.

3.6.3 Test Update operation

1. Create a new invoke in test client and select updateSampleDatabaseEmployee for Operation field.

XXXVII

2. Copy the Universal ID of the document you created earlier to the UniversalID field.

3. Set the fields that you don’t want to update as Unset. Then, enter some different values with the existing ones as shown in the figure.

Figure 42. Enter new values for the business object

4. Click Continue and check the returned business object.

XXXVIII

Figure 43. Check the business object

5. You can verify the database using the Lotus Notes client to see if the Update opera-tion executed successfully.

Figure 44. Verify the update operation

XXXIX

3.6.4 Test Retrieve operation

1. Create a new invoke in test client and select retrieveSampleDataBaseEmployee for Operation field.

2. Copy the Universal ID of the document you created earlier to the UniversalID field.

3. Click Continue and check the returned business object that the adapter retrieves from the database.

Figure 45. Check the returned business object

3.6.5 Test RetrieveAll operation

1. Create another document using these values.

Properties Name Properties Value EmployeeNumber E000002 EmployeeName Jim Brown

Address

NO.21; 4th Road; Beijing; China


PreviousReivewDates 2003-03-01; 2004-03-01

PreviousRatings 2.9;

XL

2.8

2. Create a new invoke in test client and select retrieveallSampleDatabaseEmployee for Operation field.

3. Right-click the value field and select Set To > Unset to unset all the double and date values.

Figure 46. Unset the double and the date values

4. Enter “E00000*” into the EmployeeNumber field.

Figure 47. Enter value in the employee number field

5. Click Continue and check the returned business object. The returned business ob-ject contains an array of the Form business object. You can expand them to check the data.

XLI

Figure 48. Check the business object data

3.6.6 Test Delete operation

1. Create a new invoke in test client and select deleteSampleDatabaseEmployee for Operation field.

2. Copy one of the two document’s Universal ID in database to the UniversalID field.

3. Click Continue and check the returned business object.

XLII


Check in the Lotus Notes client to see if there is only one document. The other document should be deleted.

Chapter 4 Tutorial 2: Outbound processing of documents with additional information for the selected items

4.1 User story

In this scenario, the user uses Lotus Domino to manage additional information of the com-pany employees. The EmployeeName of an employee is represented as a Lotus Domino Name and the Salary of an employee is marked as Protected in this scenario. User needs to select EmployeeName and Salary as complex item to enable isName and isProtected gen-erated in business object.


This tutorial demonstrates how to process documents with additional information using the Lotus Domino adapter. A document with additional information contains some other informa-tion of properties besides the value. The tutorial will show you both the single value and multi values of this feature.



• Ensure that you have gone through Chapter 2 and Chapter 3.

XLIII

• Ensure the Domino server is running

4.3 Check the Form using in this tutorial



The steps described in this section are similar but more detailed than section 3.3. When you read the steps, you will notice the differences in information between the two sections.

1. Check if the IBM Integration Developer is in Business Integration Perspective.

2. Create a new module named OutboundSampleComplex for this chapter.

3. Right-click the Module OutboundSampleComplex that you have created and select New > External Service.

4. In Select the Service Type or Registry window, expand the Adapters node and se-lect Lotus Domino. Click Next.

5. In Select an Adapter window, click IBM WebSphere Adapter for Lotus Domino > LotusDomino > <Your config>. Click Next.

XLIV

Figure 50. Select the Domino adapter

6. In the Select the Processing Direction window, select Outbound for this chapter. Click Next.

7. In the Discovery Configuration window, enter your Host name, DIIOP port number (63148 for default), User name, and Password. Click Next.

8. In the Find Objects in the Enterprise System window follow these steps to discover the data in Domino server as item with additional information.

a) Click Edit Query. In the Query Properties window, select the Select to set additional configurations during object selection check box and click OK.

XLV

Figure 51. Select to set additional configurations during object selection

b) Click Run Query and select SampleDatabase.nsf > Employee which was created in Chapter 2.

c) Click the arrow and in the Configuration Properties for ‘Employee’ window, select the fields that you want to be processed as item with addi-tional information. For example, Salary and EmployeeName.

XLVI

Figure 52. Select configuration properties for employee

d) Click OK, and then click Next.


10. In the Service Generation and Deployment Configuration window, enter the con-nection properties for runtime. Choose the second option for the security credential. You can also specify it later for each single interface. Click Next.

11. In the Specify Location Properties window, ensure that OutboundSampleComplex is entered in the Module field. And, change the Name field to DominoOutbound-ComplexItemInterface. Accept the defaults for other settings and click Finish.

After you complete these steps, the adapter creates an interface and several business object definitions (data types). You will also find a DominoOutboundComplexItemInterface in the Assembly diagram. Press Ctrl-S to save all the created configurations.


After doing these steps, check the data types that the adapter generates automatically.

XLVII

Figure 53. Displaying the business object structure

The adapter generates some business object types for the fields in order to process them as items with additional information. These business object types contain:

• a value field whose value is retrieved from the database,

• seven Boolean fields that indicate document properties in the Domino server,

• other fields that indicate other detailed information of the document such as Name, Type, LastModified, and ValueLength.




You can deploy the module as shown in section 3.4.

XLVIII

4.6 Test operations

You can test the module using the test client. Ensure the IBM Process Server is started. Re-start the server, if stopped.


1. Open the test client and ensure that you select the correct module, component, in-terface and operation.

• Module: OutboundSampleComplex • Component: DominoOutboundComplexItemInterface • Interface: DominoOutboundComplexItemInterface • Operation: createSampleDatabaseEmployee

Figure 54. Specify detailed properties

2. Populate the following values for input business objects as shown in the following table. Specify the input data as shown here.

Name Value Complex Properties EmployeeNumber E000001 EmployeeName Alice M. Smith IsName

Address


DateOfJoining 2001-12-01 Salary 100000 IsProtected

PreviousReivewDates2002-03-01; 2003-03-01; 2004-03-01

PreviousRatings 2.8; 2.7; 2.9

3. Click Continue and wait for server to finish the processing. After the server process is completed, you can check the output of the operation in the test client.

4. Verify the database of Domino server in the Lotus Notes client.

XLIX

Figure 55. Verify the database of the Domino server

5. You can also check the properties of the document by following these steps:

a) Right-click the document and select Document Properties. In the Docu-ment window, click the Field tab.

Figure 56. Check the data in the document

b) Select any field in the left section of the window and check the detailed data in the right section of the window.


1. Create a new invoke in test client and select retrieveSampleDatabaseEmployee for the Operation field.

L

Figure 57. Specify the detailed properties

2. Copy the Universal ID of the document you created in the section 4.5.1 to the Uni-versalID field.


LI



1. Create another document using these values.

Name Value Complex Properties EmployeeNumber E000002 EmployeeName Jim Brown IsName

Address

NO.21; 4th Road; Beijing; China

DateOfJoining 2002-05-01 Salary 150000 IsProtected

PreviousReivewDates 2003-03-01; 2004-03-01

PreviousRatings 2.9; 2.8

2. Create a new invoke in test client and select retrieveallSampleDatabaseEmployee for the Operation field.

LII


4. Type “E00000*” into the EmployeeNumber field.



The process of testing update operation of the document with additional information is simi-lar to the testing of the document without additional information. Refer to section 3.5.3 to re-view the steps.

1. Create a new invoke in test client and select updateSampleDatabaseEmployee for the Operation field.

2. Copy the Universal ID of the document you want to update to the UniversalID field.

3. Set the field that you don’t want to update as unset. Then, enter some different val-ues with the existing ones as shown in the following figure.

Figure 59. Update the module using new values along with existing values

4. Click Continue and check the document in Domino server through the Lotus Notes client.

4.6.5 Test Exists and Delete operation

The process of testing these two operations of the document with additional information is the same as testing the document without additional information. You can refer to documentation in sections 3.5.2 and 3.5.6 for more information.

LIII

Chapter 5 Tutorial 3: Outbound Processing of documents with RichText data

5.1 User story

In this scenario, the user uses Lotus Domino to manage rich text information of the company employees. The user has designed a form EmployeeWithRichtext with Lotus Domino De-signer and beside basic information each employee has a rich text Resume in the document. The Resume is represented as a Lotus Domino Rich Text in the form of Employee-WithRichtext. In the Resume field, user attaches a text file and a figure file as attachments.


This tutorial demonstrates how to process documents with Rich Text data using the Lotus Domino adapter.



• Ensure that you have gone through Chapter 2, Chapter 3, and Chapter 4.

• Ensure that the Domino server is running


To finish the tutorial in this chapter, you should have a database SampleDatabase and a form EmployeeWithRichText in this database. Refer to section 2of Appendix C to learn how to check the form.


The steps described in this section are similar but more detailed than section 3.3. When you read the steps, you will notice the differences in information between the two sections.


2. Create a new Module named OutboundSampleRichText for this chapter.

3. Right-click the Module OutboundSampleRichText that you have created and select New > External Service.

LIV

4. In the Select the Service Type or Registry window, expand the Adapters node and select Lotus Domino. Click Next.

5. In the Select an Adapter window, select IBM WebSphere Adapter for Lotus Dom-ino > Lotus Domino > <Your config>. Click Next.

6. In the Select the Processing Direction window, select Outbound for this chapter. Click Next.


8. Click Run Query, and then click SampleDatabase.nsf > EmployeeWithRichText. Refer to Chapter 2 for more information on how to create the sample database.

9. Click the arrow and to move the EmployeeWithRichText form in the Selected objects area. Click Next.


11. In the Service Generation and Deployment Configuration window, enter the con-nection properties for runtime. Choose the second option for the security credential. You can also specify it later for each single interface. Click Next.

12. In the Specify Location Properties window, ensure that OutboundSampleRichText is entered in the Module field. And, change the Name field to DominoOutboun-dRichTextInterface. Accept the defaults for other settings and click Finish.

After you complete these steps, the adapter creates an interface and several business object definitions (data types). You will also find a DominoOutboundRichTextInterface in the As-sembly Diagram. Press Ctrl-S to save all the created configurations.


After doing these steps, check the data types that the adapter generates automatically.

LV

Figure 60. Business object structure of the rich text data type

The adapter also generates a business object type for RichText type field besides items with additional information.

The business object type contains:

• a Boolean field named Overwrite that indicates the writing mode to the Domino server,

• an array of string that represents the texts of the RichText field,

• an array of Attachment that stores the attachment data, if any. The Attachment is business object type that is generated by the adapter. It contains four fields: Name, FilePath, Size, and Value. They all indicate the properties of a file. Note: The value field holds the data of a file using the hexBinary type.

Figure 61. Business object structure of rich text data type with attachment



LVI


You can deploy the module as shown in section 3.4.

5.6 Test operations


To test the Create operation, make sure that you have two or more files as attachments to test the interface. For example, “C:\Samples\Resume_E000001.jpg” and “C:\Samples\Resume_E000001.txt” files.

Figure 62. Attachments to test create operation

1. Open the test client and ensure that you select the correct Module, Component, In-terface, and Operation.

• Module: OutboundSampleRichText • Component: DominoOutboundRichTextInterface • Interface: DominoOutboundRichTextInterface • Operation: createSampleDatabaseEmployeeWithRichText

2. Populate the following values for input business objects as shown in the following

table. Specify the input data as shown here:

Name Value EmployeeNumber E000001 EmployeeName Alice M. Smith

Address



PreviousReivewDates2002-03-01; 2003-03-01; 2004-03-01

PreviousRatings 2.8; 2.7; 2.9 Texts E000001;

AliceResume Attachments C:\Samples\Resume_E000001.jpg

C:\Samples\Resume_E000001.txt

LVII

3. Click Continue and wait for the server to finish the processing. After the server process is completed, you can check the output of the operation in the test client.

4. Verify the database of Domino server in the Lotus Notes client.

Figure 63. Verify the database in the Domino server

5. You can also check the properties of the document in detail, if required.


1. Create a new invoke in the test client and select retrieveSampleDatabaseEmploy-eeWithRichText for the Operation field.

2. Copy the Universal ID of the document created in section 5.5.1 to the UniversalID field.


LVIII

Figure 64. Check the business object


1. Create another document.

2. Create a new invoke in test client and select retrieveallSampleDatabaseEmployee-WithRichText for the Operation field.


4. Enter text to the field which you want to use as an index.


LIX


The process of testing Update operation of RichText type item is similar to testing of the item with basic information. Refer to section 3.5.3 for more information.

1. Create a new invoke in the test client and select updateSampleDatabaseEmploy-eeWithRichText for the Operation field.

2. Copy the Universal ID of the document you want to update to the UniversalID field.

3. Set the field that you don’t want to update as unset. Then enter some different val-ues.

4. Click Continue and check the document in the Domino server through the Lotus Notes client.

5.6.5 Test Exists and Delete operation

The process of testing these two operations of the RichText type item is the similar to testing of the item with basic information. Refer to section 3.5.2 and 3.5.6 for more information.

Chapter 6 Tutorial 4: Inbound processing of documents

6.1 User story

In this scenario, the user uses Lotus Domino to manage basic information of the company employees. The user has designed a form Employee with Lotus Domino. To monitor any change of the Employee documents, the user configures the waldinbound.nsf to monitor Cre-ate, Update, Delete operations of the database containing Employee documents, that is, SampleDatabase.nsf.

To monitor the triggered events through WPS, the user develops an import module with some Java code which prints out the updated information of the changed employee documents.

During runtime, when another user creates, updates and deletes an employee document through the Lotus Notes, the corresponding event will be triggered and delivered to IBM Process Server endpoint and the information of the event is printed out.

This tutorial demonstrates how to import an inbound interface in a module using the Lotus Domino adapter and process Create, Update, or Delete events in the Domino server using the interface. A Create, Update, or Delete event in the Domino server triggers the interface. You can then run a bpel process or a component’s method automatically. There is no differ-ence between the events on the documents with or without the additional information. In this tutorial, a document without additional information is taken as an example.

LX



• Ensure that you have gone through Chapter 2 to Chapter 5

• Ensure that you have the database SampleDatabase.nsf and the form Employee available. In case the database or the form is unavailable, refer to documentation in Chapter 2.

6.3 Preparation for the Domino server

To test the inbound feature of the Lotus Domino adapter, complete the initial configurations the Domino server.

6.3.1 Preparation on Windows system

1. Locate the following files in their respective directories:

• the waldinbound.nsf file in the directory: <YOUR IID INSTALL DIRECTORY> \ResourceAdapters\LotusDomino_7.5.0.0\dependencies

• the waldinbound.dll file in the directory: <YOUR IID INSTALL DIRECTORY> \ResourceAdapters\ LotusDomino_7.5.0.0\dependencies\win32

Figure 65. Required directories on the Windows system

2. Locate your Domino installation directory. For example “C:\Program Files\IBM\Lotus\Domino”. Then, copy the file waldinbound.dll file to the directory.

3. Open the data folder of the directory and copy the waldinbound.nsf file to the folder.

4. Open the notes.ini file in the data folder of your Domino installation directory. In the notes.ini file append the line: EXTMGR_ADDINS=waldinbound

5. Restart the Domino server, if stopped.

6. Open the waldinbound.nsf database that you have copied to the Domino server. The name of the application is WALD Inbound Event Table. You will see a view similar to the following figure.

LXI

Figure 66. Select the configuration view to check the WALD inbound event table

7. The waldinbound.nsf database records the events that take place in the Domino server. Open the available document shown in the EventTriggerConfiguration view. Create a 'New EventTriggerConfiguration' document. Specify the following properties

1) ConnectorID - This will be the same as the connector ID you will specify in the activation spec properties for your inbound module. Ex: WALD1

2) Monitored documents- Specify the Form to be monitored in the format <Da-tabasename>:<Form name>. Example: SampleDatabase.nsf:Employee

3) Event types – Specify the operations for which you want the event trigger set.

Event triggers will be recorded for the specific event type on the specified form in the da-tabase under the EventView of the WALD Inbound Event Table. Multiple EventTriggerCon-figuration documents for multiple forms can be specified for the same ConnectorID as shown in the diagram above.

8. Open the SystemConfigurationView and click on Edit Document to modify the ex-isting log levels. Select DEBUG in the Log level field list and make sure log.nsf is checked. Press Ctrl-S to save the document. All logs are now output to the server console and the log.nsf file.

Figure 67. Configure the log level

6.3.2 Preparation on the AIX server

1. Locate the following files in their respective directories:

LXII

• the waldinbound.nsf file in the directory: <YOUR IID INSTALL DIRECTORY> \ResourceAdapters\LotusDomino_7.5.0.0\dependencies and libwaldin-bound_r.a

• the libwaldinbound_r.a file in the directory: <YOUR IID INSTALL DIRECTORY> \ResourceAdapters\ LotusDomino_7.5.0.0\dependencies\aix32

2. Locate your Domino installation directory. For example “C:\Program Files\IBM\Lotus\Domino”. Then, copy the file libwaldinbound_r.a file to the directory.

3. Open the data folder of the directory and copy the waldinbound.nsf file to the folder.

4. Open the notes.ini file in the data folder of your Domino installation directory. In the notes.ini file append the line: : EXTMGR_ADDINS=libwaldinbound_r.a

5. Restart the Domino server, if stopped.

6. Open the waldinbound.nsf database that you have copied to the Domino server. The name of the application is WALD Inbound Event Table. You will see a view similar to the following figure.

7. The waldinbound.nsf database records the events that take place in the Domino server. Open the available document shown in the Configuration view.

8. Select DEBUG in the Log level field list. Make sure that all other fields are config-ured as shown in the following figure. Press Ctrl-S to save the document.



6.5 Create an inbound interface into a Module using the Lotus Domino adapter


2. Create a new Module named InboundSampleBasic for this chapter.

3. Right-click the Module InboundSampleBasic that you have created and select New > External Service.



6. In the Select the Processing Direction window, select Inbound for this chapter. Click Next.

LXIII

Figure 68. Select the inbound processing


8. In the Find Objects in the Enterprise System window, click Run Query, and then select SampleDatabase.nsf > Employee which was created in Chapter 2.

9. Click the arrow icon to move the Employee form in the Selected objects area. Click Next.


11. In the Service Generation and Deployment Configuration window, enter the con-nection properties for runtime. Choose the second option for the security credential. Click Advanced, and then click to open the Event delivery configuration section.

12. Enter WALD1 in the Adapter Instance for event filtering field. This should be the same or one of the ConnectorID values specified in EventTriggerConfiguration in the WALD Inbound Event Table. You can also specify the value later for each single in-terface. Click Next.

LXIV

Figure 69. Enter the value in the adapter instance for event filtering field

13. In the Specify Location Properties window, ensure that InboundSampleBasic is en-tered in the Module field. Also, change the Name field to DominoInbound-BasicItemInterface. Accept the defaults for other settings and click Finish.

After you complete these steps, the adapter creates an interface. You will also find a Domi-noInboundBasicItemInterface in the Assembly Diagram. Press Ctrl-S to save all the created configurations.

Figure 70. Check the assembly diagram for the inbound sample

The Inbound Interface is ready but it requires a target component to test it. When the inter-face is triggered, the component is invoked. The component may be a process or a Java component. In this example, a simple Java component is used to output some information to the console.

1. Open the Assembly diagram and drag a Java component to the diagram. Type the name of the Java component as PrintInboundBO.

LXV

Figure 71. Select the Java component

2. Connect DominoInboundBasicItemInterface and PrintInboundBO. Click OK in the Add Wire window. A wire is drawn between the interface and the component.

Figure 72. Add the wire

3. Double-click the component, click Yes in the confirmation window.

Figure 73. Confirm the component selection

4. Select the default package and click OK in the Generation Implement window.

5. In the new window, the implementation class of PrintboundBO: PrintInboundBOImpl is shown. Copy the following codes and replace them with the three methods of the class.

public void emitCreateAfterImageSampleDatabaseEmployee(

DataObject emitCreateAfterImageSampleDatabaseEmployee-Input) {

DataObject in-put=emitCreateAfterImageSampleDatabaseEmployeeInput;

System.out.println("**********Create Event**********");

LXVI

System.out.println("UnivseralID: "+input.getString("UniversalID"));

System.out.println("Employee name: "+input.getString("EmployeeName"));

}

public void emitUpdateAfterImageSampleDatabaseEmployee(

DataObject emitUpdateAfterImageSampleDatabaseEmployee-Input) {

DataObject in-put=emitUpdateAfterImageSampleDatabaseEmployeeInput;

System.out.println("**********Update Event**********");


System.out.println("Employee name: "+input.getString("EmployeeName"));

}

public void emitDeleteAfterImageSampleDatabaseEmployee(

DataObject emitDeleteAfterImageSampleDatabaseEmployee-Input) {

DataObject in-put=emitDeleteAfterImageSampleDatabaseEmployeeInput;

System.out.println("**********Delete Event**********");


}

6. Press Ctrl-S to save the class. Close the window and save the assembly diagram. The Assembly Diagram will look similar to the following figure.

LXVII

Figure 74. Wire the interface with the component





Before you deploy the module, make sure the Domino server is running properly. Refer to documentation in section 3.4 for information on deploying the module.

6.7 Test Interface

This section demonstrates the testing of inbound interface by creating, updating, and deleting a document. These activities generate a trigger that invokes the interface’s operations. The PrintInboundBO’s method is invoked in the process. You can check the output from the con-sole.

6.7.1 Prerequisites

Before starting the tests, perform the following tasks:

• Open the Console view in IBM Integration Developer.

• Click to clear the console


1. Open Lotus Notes client, and then open the SampleDatabase database.

2. Click Create from the menu bar and select Employee.

LXVIII

Figure 75. Select the employee form

Enter the value in the document as shown here.

Figure 76. Enter new values in the employee form

3. Press Ctrl-S to save the document.

4. Change to the Console view in the WID task, and check if new lines are shown as output in the console.

Figure 77. Check if the new employee is added in the database



2. Double-click the document you created in the previous section.

LXIX

3. Double-click the form to modify it. Enter the content as shown in the following figure. Press Ctrl-S to save the document.

Figure 78. Update the employee salary details in the form


Figure 79. Check the update event in the console



2. Click the document you created in the section 6.5.2 to select it.

3. Press Shift and Delete together to delete the document.


LXX

Check if the delete event was successful

Chapter 7 Tutorial 5: Inbound processing of documents with RichText data

7.1 User story

In this scenario, the user uses Lotus Domino to manage rich text information of the company employees. The user has designed a form EmployeeWithRichtext with Lotus Domino De-signer and beside basic information each employee has a rich text Resume in the document. To monitor any change of the EmployeeWithRichtext documents, the user configures the waldinbound.nsf to monitor Create, Update, Delete operations of the database containing EmployeeWithRichtext documents, that is, SampleDatabase.nsf.

To monitor the triggered events through WPS, the user develops an import module with some Java code which prints out the updated information of the changed employee documents.

During runtime, when another user creates, updates or deletes an employee document through the Lotus Notes, the corresponding event will be triggered and delivered to IBM Process Server endpoint and the information of the event is printed out. When creating or up-dating the document through Lotus Notes, the user set the Resume field by input text and at-taching files.

The scenario of inbound processing data with RichText type is a common occurrence in a practical business solution. This tutorial demonstrates to you how to import an inbound inter-face in a module using the Lotus Domino adapter to process RichText data in Domino server.



• Ensure that you have gone through Chapter 2 to Chapter 6

• Ensure that your Domino server is running

LXXI


To finish the tutorial in this chapter, you should have a database SampleDatabase and a form EmployeeWithRichText in this database. Refer to section 2 of Appendix C to learn how to check the form. You will also need to add an EventTriggerConfiguration Document for WALD1, SampleDatabase.nsf:EmployeeWithRichText in the WALD Inbound Event Table.

7.4 Create an inbound interface into a Module using the Lotus Domino adapter


2. Create a new module named InboundSampleRichText for this chapter

3. Right-click the module InboundSampleRichText which you have created and select New > External Service.



6. In the Select the Processing Direction window, select Inbound for this chapter. Click Next.


8. In the Find Objects in the Enterprise System window, click Run Query, and then select SampleDatabase.nsf > EmployeeWithRichText which was created in Chap-ter 2.

9. Click the arrow icon and move EmployeeWithRichText form in the Selected objects area. Click Next.

LXXII

Figure 80. Move the employee with rich text form to the selected objects area


11. In the Service Generation and Deployment Configuration window, enter the con-nection properties for runtime. Choose the second option for the security credential. Click Advanced, and then click to open the Event delivery configuration section.

12. Enter WALD1 in the Adapter Instance for event filtering field. You can also specify the value later for each single interface. Click Next.

13. In the Specify Location Properties window, ensure that InboundSampleRichText is entered in the Module field. Also, change the Name field to DominoInboundRichTex-tInterface. Accept the defaults for other settings and click Finish.

After you complete these steps, the adapter creates an interface. Also, you will find a Domi-noInboundRichTextInterface in Assembly diagram. Press Ctrl-S to save all the created con-figurations.

LXXIII

Figure 81. Displaying the domino inbound rich text interface in the assembly diagram

The Inbound Interface is ready but it requires a target component to test it. When the inter-face is triggered, the component is invoked. The component may be a process or a Java component. In this example, a simple Java component is used to output some information to the console.

1. Open the Assembly diagram and drag a Java component to the diagram. Type the name of the Java component as PrintInboundBOWithRichText.

2. Connect DominoInboundRichTextInterface and PrintInboundBOWithRichText. Click OK in the Add Wire window. A wire is drawn between the interface and the compo-nent.

3. Double-click the component, and click Yes in the confirmation window.

4. Select the default package and click OK for the Generation Implement window.

5. In the new window, the implementation class of PrintInboundBOWithRichText is shown. Perform the following tasks on the PrintInboundBOWithRichTextImpl class.

a) Add import java.util.List; to the beginning of the class file.

b) Copy the following codes and replace them with the three methods of the class.

public void emitCreateAfterImageSampleDatabaseEmployeeWithRichText(

DataObject emitCreateAfterImageSampleDatabaseEmployee-WithRichTextInput) {

DataObject input= emitCreateAfterImageSampleDatabaseEmployee-WithRichTextInput;

System.out.println("***********Create Event***********");

System.out.println("UniversalID: "+input.getString("UniversalID"));

DataObject richtext=input.getDataObject("Resume");

System.out.println("Texts: "+richtext.getString("Texts"));

List attachmentList=richtext.getList("Attachments");

for(int i=0;i<attachmentList.size();i++){

DataObject attachment=(DataObject)attachmentList.get(i);

System.out.println("Attachment No."+i);

LXXIV

System.out.println("Name: "+attachment.getString("Name"));

System.out.println("FilePath: "+attachment.getString("FilePath"));

System.out.println("Size: "+attachment.getInt("Size"));

}

}

public void emitUpdateAfterImageSampleDatabaseEmployeeWithRichText(

DataObject emitUpdateAfterImageSampleDatabaseEmployee-WithRichTextInput) {

DataObject input= emitUpdateAfterImageSampleDatabaseEmployee-WithRichTextInput;

System.out.println("***********Update Event***********");

System.out.println("UniversalID: "+input.getString("UniversalID"));

DataObject richtext=input.getDataObject("Resume");

System.out.println("Texts: "+richtext.getString("Texts"));

List attachmentList=richtext.getList("Attachments");

for(int i=0;i<attachmentList.size();i++){

DataObject attachment=(DataObject)attachmentList.get(i);

System.out.println("Attachment No."+i);

System.out.println("Name: "+attachment.getString("Name"));

System.out.println("FilePath: "+attachment.getString("FilePath"));

System.out.println("Size: "+attachment.getInt("Size"));

}

}

public void emitDeleteAfterImageSampleDatabaseEmployeeWithRichText(

DataObject emitDeleteAfterImageSampleDatabaseEmployee-WithRichTextInput) {

System.out.println("***********Delete Event***********");

LXXV

System.out.println("UniversalID: "+emitDeleteAfterImageSampleDatabaseEmployeeWithRichTextInput.getString("UniversalID"));

}

6. Press Ctrl-S to save the class. Close the window and save the assembly diagram. The Assembly Diagram will look similar to the following figure.

Figure 82. Connect the interface to the target component





Before you deploy the module, make sure the Domino server is running properly. You can deploy the module like section 3.4 shows.

7.6 Test Interface

This section demonstrates the testing of inbound interface by creating, updating, and deleting a document. These activities generate a trigger that invokes the interface’s operations. The PrintInboundBOWithRichText’s method is invoked in the process. You can check the output from the console.

7.6.1 Prerequisites

Before starting the tests, perform the following tasks:

• Open the Console view in IBM Integration Developer.

• Click to clear the console

• Make sure you have two or more files as attachments to test the interface. For exam-ple, “C:\Samples\Resume_E000001.jpg” and “C:\Samples\Resume_E000001.txt”.

LXXVI

Figure 83. Files as attachments to test the interface



2. Click Create from the menu bar and select EmployeeWithRichText form.

3. Enter values to the form’s other fields.

4. Enter values in the Resume field. Enter the information as described in the following steps:

a) Type some information. You can start a new line to enter text.

b) Click the attachment icon to add an attachment to the field

c) In the Create Attachments window, browse to the directory where your test files are present. Select a test file and click Create.

LXXVII

Figure 84. Select files for attachment

d) Complete the process of adding all the attachments that you want to add.

5. The field will show information similar to the figure. Press Ctrl-S to save the docu-ment.

LXXVIII

Figure 85. Attachments to the employee form

6. Change to the Console view in the WID task, and you can find new lines are shown as output in the console.

Figure 86. Console view for the create event



2. Double-click the document you created in previous section.

3. Double-click the form to modify it. Enter the content as shown in the following figure. Press Ctrl-S to save the document.

LXXIX

Figure 87. Update the attachments


Figure 88. Console view of the update event



LXXX

2. Double-click the document you created in the section 7.5.2 to select it.

3. Press Shift and Delete together to delete the document.


Console view of the delete event

Chapter 8 Troubleshooting

8.1 Allow browsing of the database through HTTP

8.1.1 Symptom

During the EMD process, when you click the Run Query option, an exception message is displayed with the information: “NotesException: Server access denied”.

8.1.2 Cause

The Domino server does not allow HTTP clients to browse databases.

LXXXI

8.1.3 Resolution

Configure the Domino server to allow HTTP clients to browse databases.

1. In IBM Domino Administrator, click the Configuration tab.

2. Click to expand the Server node in the left pane, and then click the Current Server Document.

3. Click the Internet Protocols tab. The HTTP tab is selected by default.

4. In the R5 Basics section, select Yes to allow HTTP clients to browse Domino da-tabases. Refer to documentation in section 2.2 for more information.

8.2 Configure Domino server’s Internet host name

8.2.1 Symptom

During EMD process, when you click the Run Query option, an exception message is dis-played with the information: “org.omg.CORBA.NO_PERPISSION”.

8.2.2 Cause

The domino server's Internet host name is not the same as the machine host name.

8.2.3 Resolution

Configure the Domino server’s Internet host name as same as the machine host name.



3. In the Basics tab, for Fully qualified Internet host name field, set the value as same as the machine host name of the server.

8.3 Idle session timeout

8.3.1 Symptom

During EMD process, when you click the Run Query option, an exception message or dur-ing the run time process, an exception or Notes fault is generated. The exception message “NotesException: Object no longer exists on server” is displayed.

LXXXII

8.3.2 Cause

The session connecting to Lotus Domino times out due user inactivity for a long time on ei-ther the EMD or the runtime.

8.3.3 Resolution

a) Change the "Idle session time" of the Domino server, that will impact both EMD and runtime processes.



3. Click the Internet Protocols tab, and then click the DIIOP tab.

4. In the Basics section, set the desired value in the Idle session timeout field.

b) Enable the retry on connection failure for the module during EMD, which will impact only for runtime processes after re-deployment.

1. In WID, during EMD configuration, select Managed Connection Factory Prop-erties > Additional configuration > Maximum retries in case of system connection failure.

Set the value to bigger than 0. This enables the WPS to retry with new connections to Lotus Domino when there is connection problem.

Appendix A Create a database, form, and field in the Domino server

1 Create a database

This subsection tells you how to create a database in Lotus Domino.

1. Start the Lotus Domino Designer and log in.

2. Right-click the Application area on the left pane, and then click New Application.

LXXXIII

Figure 89. Create a new application (database)

3. Select the Domino server from the Server list (or you can create a server on your lo-cal disk) in the New Application window.

4. Type SampleDatabase in the Title field (you can change to another name). Then, type SampleDatabase.nsf in the File field (you can specify a desired file name). Click OK.

LXXXIV

Figure 90. Configure the new application

5. After you have completed creating the database, check if it appears similar to the fol-lowing figure.

LXXXV

Figure 91. Sample database contents

2 Create a form in the database

In this subsection, you will know how to create a form

1. Expand the SampleDatabase and right-click Forms. Then, click New Form.

LXXXVI

Figure 92. Create a new Form

2. Type the desired form name in the Name field.

Figure 93. Enter a name for the Form

LXXXVII

3 Create a field in the Form

1. Click the Create Field on the menu bar.

Figure 94. Create a field in the Form

2. In the Field window, type the desired name in the Name field.

Figure 95. Enter a field name

3. Select the field type for this field from the Type list.

LXXXVIII

Figure 96. Select the field type

4. Select the Allow multiple values check box if you want the field to have multiple values.

Figure 97. Select to allow multiple values

5. Click the Advanced tab and choose a security option for the field.

LXXXIX

Figure 98. Select a security option

Αππενδιξ Β Verify document through Lotus Notes

1 Verify the created document

After you create a document using outbound interface, you can verify the database through a Lotus Notes client.

1. Open Lotus Notes client and click Open > Applications > Workspace to open a workspace.

XC

Figure 99. Open a workspace

2. Right-click the workspace and select Open Application.

Figure 100. Open an application in the workspace

3. In the Open Application window, select the Domino server and the SampleData-base that you created earlier. Click Open.

XCI

Figure 101. Select the Domino server and the sample database

4. You can find the documents you have created in the database.

Figure 102. View the document in the database

5. Double-click the database to see the data you entered using the test client of IBM In-tegration Developer. This indicates that the Create operation was successful.

Figure 103. Check the output of the create operation

XCII

2 Check the Universal ID

You can check the Universal ID of the document that you created by following these steps:

1. Right-click the document and select Document Properties.

Figure 104. Open to configure the document properties

2. In the Document window, click the Meta tab.

XCIII

Figure 105. Click the Meta tab in the document properties

3. In the Identifier field, the last string of the value after a “/” is the Universal ID of the document. Refer to the selected numbers in the figure 60.

Figure 106. Check the universal ID of the document

XCIV

Αππενδιξ Χ Check the form created in section 2.3

1 Check the form employee

To complete the tutorials one, two, and four, you should have a database SampleData-base.nsf and a form Employee. The form should be similar to the contents in the following table.

Field Name Field Type Multi-Value Security Options EmployeeNumber Text False None EmployeeName Names False None Address Text True None DateOfJoining Date False None Salary Number False Editor access to use PreviousReviewDates Date True None PreviousRatings Number True None

Figure 107. Check the employee form

If you do not have the database of the form, please refer to documentation in section 2.3.

2 Check the form EmployeeWithRichText

To complete the tutorials three and five, you need the database SampleDatabase.nsf and a form EmployeeWithRichText. The form should be similar to the contents in the following ta-ble.

Field Name Field Type Multi-Value Security Options EmployeeNumber Text False None EmployeeName Names False None Address Text True None DateOfJoining Date False None Salary Number False Editor access to use

XCV

PreviousReviewDates Date True None PreviousRatings Number True None Resume RichText None

Figure 108. Structure of the employee form

If you do not have the database of the form, refer to documentation in section 2.2.

Αππενδιξ Δ Import the sample to your work-space

You can directly import the sample to your workspace for testing. The following steps describe how to import the sample to your workspace.

1. Click File > Import.

XCVI

Figure 109. Select the import option

2. In the Import window, select Other > Project Interchange. Click Next.

XCVII

Figure 110. Select project interchange

3. In the Import Project Interchange Contents window, click Browse to browse the sam-ple files (for example, Tutoria1.zip) and select the project OutboundSampleBasic. Click Finish.

XCVIII

Figure 111. Import project interchange contents

4. If the J2EE application project does not exist, select the business integration project you have imported, for example, OutboundSampleBasic, invoke Build Project to generate the J2EE application projects, for example, OutboundSampleBasicApp.

XCIX

Figure 112. Build business integration project

5. Change the connection properties in Managed Connection Factory Properties for Out-bound module or connection properties in Managed Connection Factory Properties Acti-vationSpec Properties for Inbound module if your connection properties of Lotus Dom-ino are different from the connection properties shown in this document.

C

Figure 113. Change connection properties

CI

Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document in other countries. Consult your local IBM representative for information on the products and services currently avail-able in your area. Any reference to an IBM product, program, or service is not intended to state or imply that only that IBM product, program, or service may be used. Any functionally equivalent product, program, or service that does not infringe any IBM intellectual property right may be used instead. However, it is the user's responsibility to evaluate and verify the operation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matter described in this document. The furnishing of this document does not grant you any license to these patents. You can send license inquiries, in writing, to:

IBM Director of Licensing

IBM Corporation

North Castle Drive

Armonk, NY 10504-1785

U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBM Intellectual Prop-erty Department in your country or send inquiries, in writing, to:

IBM World Trade Asia Corporation Licensing

2-31 Roppongi 3-chome, Minato-ku

Tokyo 106-0032, Japan

The following paragraph does not apply to the United Kingdom or any other country where such provisions are inconsistent with local law:

INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Some states do not allow disclaimer of express or implied warranties in certain transactions, there-fore, this statement may not apply to you.

CII

This information could include technical inaccuracies or typographical errors. Changes are periodi-cally made to the information herein; these changes will be incorporated in new editions of the pub-lication.

IBM may make improvements and/or changes in the product(s) and/or the program(s) described in this publication at any time without notice.

Any references in this information to non-IBM Web sites are provided for convenience only and do not in any manner serve as an endorsement of those Web sites.

The materials at those Web sites are not part of the materials for this IBM product and use of those Web sites is at your own risk.

IBM may use or distribute any of the information you supply in any way it believes appropriate with-out incurring any obligation to you.

Licensees of this program who wish to have information about it for the purpose of enabling: (i) the exchange of information between independently created programs and other programs (including this one) and (ii) the mutual use of the information which has been exchanged, should contact:

IBM Corporation Department

2Z4A/SOM1 294 Route 100

Somers, NY 10589-0100 U.S.A.

Information concerning non-IBM products was obtained from the suppliers of those products, their published announcements or other publicly available sources. IBM has not tested those products and cannot confirm the accuracy of performance, compatibility or any other claims related to non-IBM products. Questions on the capabilities of non-IBM products should be addressed to the sup-pliers of those products.

This information contains examples of data and reports used in daily business operations. To illus-trate them as completely as possible, the examples include the names of individuals, companies, brands, and products. All of these names are fictitious and any similarity to the names and ad-dresses used by an actual business enterprise is entirely coincidental.

COPYRIGHT LICENSE

This information contains sample application programs in source language, which illustrate pro-gramming techniques on various operating platforms. You may copy, modify, and distribute these

CIII

CIV

sample programs in any form without payment to IBM, for the purposes of developing, using, mar-keting or distributing application programs conforming to the application programming interface for the operating platform for which the sample programs are written. These examples have not been thoroughly tested under all conditions. IBM, therefore, cannot guarantee or imply reliability, service-ability, or function of these programs.

If you are viewing this information softcopy, the photographs and color illustrations may not appear.

Programming interface information

Programming interface information, if provided, is intended to help you create application software using this program.

General-use programming interfaces allow you to write application software that obtain the services of this program's tools.

However, this information may also contain diagnosis, modification, and tuning information. Diag-nosis, modification and tuning information is provided to help you debug your application software.

Warning

Do not use this diagnosis, modification, and tuning information as a programming interface because it is subject to change.

Trademarks

IBM, the IBM logo, and ibm.com are trademarks or registered trademarks of International Business Machines Corporation in the United States, other countries, or both. These and other IBM trade-marked terms are marked on their first occurrence in this information with the appropriate symbol (® or ™), indicating US registered or common law trademarks owned by IBM at the time this infor-mation was published. Such trademarks may also be registered or common law trademarks in other countries. A complete and current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml

Linux is a registered trademark of Linus Torvalds in the United States, other countries, or both.

Microsoft and Windows are trademarks of Microsoft Corporation in the United States, other coun-tries, or both.

Java and all Java based trademarks and logos are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and other countries.

Other company, product, or service names may be trademarks or service marks of others.

This product includes software developed by the Eclipse Project (http://www.eclipse.org).

http://www.ibm.com/legal/copytrade.shtml_

ibm websphere adapter for lotus domino 7.5.0 · websphere adapter for lotus domino is a j2ee...

Documents