· Step 9: Select Scheduling Options..... 202 Step 8: Select Options..... 202 Step 7: Name the...

��

��

�� !"#$�%�&''&�(��)��

(��*��*��+��,��-��*�� .�'&!/&

.��- ��-��

��

)� ��0�� 1��1��)� ��)� ��2�� *�� (��2�� )� ��3(2�4��1��567��8�9��6��6��+�� (��(��1��(��*� ��1�� 1��*:(��1��; ��!�&�<�,�� =��*��*��*� �� 8��(��)�� 5�� *�� ,*5&�>��?��?��8��.�7��)�&��,*<"'�� *�� =*�� *�� ,*5&�?�� *1.�� 8��)�&5&��)�&5/''��-*5@'''��8�� A �� 5�� 8��A �� *��5�� *��

.��8��

��

AB�*�),��21A.A�,1��*�?-,;�)2)�6,-�-262-21�2�?�-?,*2*�,1(C��>B�(2�266,-A*>2-2��.)2�A,�;2-�6C�AB2��,�?(2A212**�.1)�.��-.�C�,6�AB2��16,-�.A�,1�,1A.�12)��1�AB�*�),��21A.A�,1��AB�*�),��21A.A�,1��*�?-,;�)2)�D.*��*E>�AB,�A�.1C�>.--.1AC�>B.A*,2;2-�.1)�A,�AB2��.7��27A21A�?2-��AA2)�(,A�*�)�*�(.��*�.((��?(�2)�>.--.1A�2*��1�(�)�1+�>�AB,�A�(��A.A�,1�AB2��?(�2)�>.--.1A�2*�,6��2-�B.1A.��(�AC��1,1�16-�1+2�21A�.1)�6�A12**�6,-�.?.-A��(.-�?�-?,*2��>�AB�-2*?2�A�A,�AB2�*.�2��(,A�*�*B.((�1,A��2�-2*?,1*��(26,-�.1C�).�.+2*��1�(�)�1+�>�AB,�A�(��A.A�,1��)�-2�A��1)�-2�A��,1*2:�21A�.(�,-��1��)21A.(�).�.+2*��.-�*�1+�,�A�,6�AB2��*2�,6��,-�,AB2->�*2-2(.A2)�A,��AB�*�),��21A.A�,1�,-�.1C�,AB2-�),��21A.A�,1�1,A>�AB*A.1)�1+�.1CAB�1+�A,�AB2��,1A-.-C��1,AB�1+��,1A.�12)��1�AB�*),��21A.A�,1�,-�.1C�,AB2-�),��21A.A�,1��*��1A21)2)�A,��1,-�*B.((�B.;2AB2�2662�A�,6��-2.A�1+�.1C�>.--.1A�2*�,-�-2?-2*21A.A�,1*�6-,��(,A�*�3,-��A**�??(�2-*�,-�(��21*,-*4��,-�.(A2-�1+�AB2�A2-�*�.1)��,1)�A�,1*�,6�AB2.??(��.�(2�(��21*2�.+-22�21A�+,;2-1�1+�AB2��*2�,6�AB�*�*,6A>.-2�

16Web-based Application

Considerations . . . . . . . . . . . . . . . . . . .

15

Using Advanced RealTime Activitiesin a Clustered Domino ServerEnvironment . . . . . . . . . . . . . . . . . . . . .

15Advanced RealTime Activity:

Indexing Increases Performance . . . . . .

14General Performance Considerations . . . . .

13Sample LEI Configuration with

Processing Times . . . . . . . . . . . . . . . . .

13Performance . . . . . . . . . . . . . . . . . . . . . . . . . .

11Accessibility . . . . . . . . . . . . . . . . . . . . . . . . . .

10General LEI Terms . . . . . . . . . . . . . . . . . . . . .

9User Documentation . . . . . . . . . . . . . . . . . .

9Field-level Help . . . . . . . . . . . . . . . . . . . . . .

9Pop-up Help . . . . . . . . . . . . . . . . . . . . . . . .

9User Assistant Help . . . . . . . . . . . . . . . . . . .

9Obtaining Help and Opening User

Documentation . . . . . . . . . . . . . . . . . . . .

8LEI Logs . . . . . . . . . . . . . . . . . . . . . . . . . . .

7LEI Activities . . . . . . . . . . . . . . . . . . . . . . . .

6Lotus Connectors . . . . . . . . . . . . . . . . . . . . .

3LEI Architecture . . . . . . . . . . . . . . . . . . . . .

3Introduction to LEI . . . . . . . . . . . . . . . . . . . . . .

3Getting Started with LEI . . . . . . . . . . . . . . . . . .

1Organization of this Manual . . . . . . . . . . . . . . .

11 Introduction . . . . . . . . . . . . . . . . . . . . . .

xiiContact and Support Information . . . . . . .

xiRelated Documentation . . . . . . . . . . . . . . .

xiPreface . . . . . . . . . . . . . . . . . . . . . . . . . . . .

25From LEI Administrator Database . . . . . . .

25WRKACTJOB on iSeries . . . . . . . . . . . . . .

24Show Task from Domino Console . . . . . . .

24Determining if LEI Server is Running on

iSeries . . . . . . . . . . . . . . . . . . . . . . . . . .

24By stopping the Domino Server . . . . . . . . .

24From the LEI Administrator . . . . . . . . . . .

23From the Domino Console . . . . . . . . . . . . .

23Stopping the LEI Server on iSeries . . . . . . . . .

23Starting the LEI Server Manually . . . . . . . .

23Starting the LEI Server

Automatically . . . . . . . . . . . . . . . . . . . .

23Starting and Running the LEI Server on

iSeries . . . . . . . . . . . . . . . . . . . . . . . . . .

22Understanding the leiclean Script for

UNIX and iSeries . . . . . . . . . . . . . . . . .

21Considerations . . . . . . . . . . . . . . . . . . . . .

21Running LEI as a Domino Addin Task . . . . . .

20Executing LEI Server Commands from

the Administrator . . . . . . . . . . . . . . . . .

20Executing LEI Server Commands From

the Console . . . . . . . . . . . . . . . . . . . . . .

19Starting the LEI Server . . . . . . . . . . . . . . . . . .

192 Starting and Running theLEI Server . . . . . . . . . . . . . . . . . . . . . . . . .

17Term Comparison for iSeries . . . . . . . . . . .

17Languages Support on iSeries . . . . . . . . . .

16LEI Server Running Window on

iSeries . . . . . . . . . . . . . . . . . . . . . . . . . .

16LEI Server on iSeries . . . . . . . . . . . . . . . . .

16LEI on the iSeries . . . . . . . . . . . . . . . . . . . . . .

iii

Contents

55Lotus Connectors Supplied with LEI . . . . . . .

554 Introduction to Connectors . . . . . .

53LEI Script Vault . . . . . . . . . . . . . . . . . . . . . . .

52Operation Log . . . . . . . . . . . . . . . . . . . . . .

51Activity Log . . . . . . . . . . . . . . . . . . . . . . . .

50Server Log . . . . . . . . . . . . . . . . . . . . . . . . .

50LEI Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

48Server Configuration . . . . . . . . . . . . . . . . .

47Administrator Configuration . . . . . . . . . . .

47LEI Configuration Documents . . . . . . . . . . . .

47Configuring Browsing . . . . . . . . . . . . . . . .

45Understanding Basic Browsing . . . . . . . . . . .

45Save and Exit . . . . . . . . . . . . . . . . . . . . . . .

44Start! . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

44Edit Document . . . . . . . . . . . . . . . . . . . . .

44Author Privileges . . . . . . . . . . . . . . . . . . .

43Activity Document Action Bar . . . . . . . . . . . .

43Deleting Documents . . . . . . . . . . . . . . . . .

42Editing Existing Documents . . . . . . . . . . .

40Creating New LEI Documents . . . . . . . . . .

40Creating, Editing, and Deleting

Documents . . . . . . . . . . . . . . . . . . . . . .

38Actions . . . . . . . . . . . . . . . . . . . . . . . . . . .

38Create . . . . . . . . . . . . . . . . . . . . . . . . . . . .

38LEI Administrator Menu Commands . . . . . . .

31LEI Administrator Navigator and View

Options . . . . . . . . . . . . . . . . . . . . . . . . .

29LEI Administrator Action Bar . . . . . . . . . . . . .

28Configuring Administrator Security . . . . .

28LEI Administrator Database . . . . . . . . . . . . . .

27LEI Administrator . . . . . . . . . . . . . . . . . . . . .

273 LEI Administrator . . . . . . . . . . . . . . .

82Activity Logging . . . . . . . . . . . . . . . . . . . . . .

81Moving Text List Data over Different

Platforms . . . . . . . . . . . . . . . . . . . . . . .

79Example: Notes to DB2 Direct

Transfer Activity . . . . . . . . . . . . . . . . . .

78Stored Procedures and Output

Parameters . . . . . . . . . . . . . . . . . . . . . .

77When Field Numbers Don’t Match . . . . . .

77According to User Definition . . . . . . . . . . .

77According to Field Position . . . . . . . . . . . .

77According to Field Names . . . . . . . . . . . . .

76Data Mapping . . . . . . . . . . . . . . . . . . . . . . . .

76Additional iSeries Considerations . . . . . . .

75General Considerations . . . . . . . . . . . . . . .

75Command Line Execution of Activities . . . . . .

71Integrated Credentials Database . . . . . . . .

70Virtual Agents Activity . . . . . . . . . . . . . . .

70Virtual Documents Activity . . . . . . . . . . . .

69Virtual Fields Activity . . . . . . . . . . . . . . . .

69Advanced RealTime Activities . . . . . . . . . . . .

65Scheduling . . . . . . . . . . . . . . . . . . . . . . . . .

62Overview of Scheduling . . . . . . . . . . . . . .

62Activity Scheduling Options . . . . . . . . . . . . . .

62Category and Comments . . . . . . . . . . . . . .

61Scheduling . . . . . . . . . . . . . . . . . . . . . . . . .

60General Options . . . . . . . . . . . . . . . . . . . .

59Activity Name and Status . . . . . . . . . . . . .

59Author Privileges Action Button . . . . . . . .

59Common Activity Fields and Buttons . . . . . . .

58Browsing Connections from within

an Activity . . . . . . . . . . . . . . . . . . . . . .

58Creating Activities . . . . . . . . . . . . . . . . . . . . .

57Introduction to Activity Documents . . . . . . . .

575 Introduction to LEI Activities . . . . . . . . . . . . . . . . . . . . . .

iv IBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide

100Archive Target Data Options . . . . . . . . . .

99Archive Precision Options . . . . . . . . . . . . .

98Archive Selection Options . . . . . . . . . . . . .

97Mapping . . . . . . . . . . . . . . . . . . . . . . . . . .

96Target . . . . . . . . . . . . . . . . . . . . . . . . . . . .

96Source . . . . . . . . . . . . . . . . . . . . . . . . . . . .

95Identification . . . . . . . . . . . . . . . . . . . . . . .

95Archive Activity Document . . . . . . . . . . . . . .

94How to Create an Archive Activity . . . . . . . . .

94Combining an Archive Activity with

other Activities . . . . . . . . . . . . . . . . . . .

93When to Use the Archive Activity . . . . . . . . .

93Introduction to the Archive Activity . . . . . . . .

938 Archive Activity . . . . . . . . . . . . . . . . .

91Purge Log Options . . . . . . . . . . . . . . . . . .

90Identification . . . . . . . . . . . . . . . . . . . . . . .

90Admin Purge Log Activity Document . . . . . .

89Saving Selected Logs before Purging . . . . .

89How to Create an Admin Purge Log

Activity . . . . . . . . . . . . . . . . . . . . . . . . .

89When to Use the Admin Purge Log

Activity . . . . . . . . . . . . . . . . . . . . . . . . .

89Introduction to the Admin Purge Log

Activity . . . . . . . . . . . . . . . . . . . . . . . . .

897 Admin Purge Log Activity . . . . . . .

87Backup Options . . . . . . . . . . . . . . . . . . . . .

87Identification . . . . . . . . . . . . . . . . . . . . . . .

86Admin Backup Activity Document . . . . . . . . .

85How to Create an Admin Backup

Activity . . . . . . . . . . . . . . . . . . . . . . . . .

85When to Use the Admin Backup

Activity . . . . . . . . . . . . . . . . . . . . . . . . .

85Introduction to the Admin Backup

Activity . . . . . . . . . . . . . . . . . . . . . . . . .

856 Admin Backup Activity . . . . . . . . . .

118Using the Lotus Connector for Notes . . . .

118Using Stored Procedures and Output

Parameters . . . . . . . . . . . . . . . . . . . . .

118Direct Transfer Activity Considerations . . . .

117Performance Options . . . . . . . . . . . . . . . .

115Target Data Options . . . . . . . . . . . . . . . .

114Source Data Options . . . . . . . . . . . . . . . .

113Precision Options . . . . . . . . . . . . . . . . . .

113Direct Transfer Options . . . . . . . . . . . . . .

112Mapping . . . . . . . . . . . . . . . . . . . . . . . . .

111Target . . . . . . . . . . . . . . . . . . . . . . . . . . .

111Source . . . . . . . . . . . . . . . . . . . . . . . . . . .

110Identification . . . . . . . . . . . . . . . . . . . . . .

110Direct Transfer Activity Document . . . . . . . .

109How to Create a Direct Transfer

Activity . . . . . . . . . . . . . . . . . . . . . . . .

109When to Use a Direct Transfer Activity . . . .

109Introduction to the Direct Transfer

Activity . . . . . . . . . . . . . . . . . . . . . . . .

10910 Direct Transfer Activity . . . . . . .

107Command Example Issuing

Operating System Commands . . . . . . .

105Command Activity Using a Notes

Agent . . . . . . . . . . . . . . . . . . . . . . . . .

104Command Activity Using SQL . . . . . . . .

104Command Activity Examples . . . . . . . . . . . .

103Command . . . . . . . . . . . . . . . . . . . . . . . .

103Connection . . . . . . . . . . . . . . . . . . . . . . .

103Identification . . . . . . . . . . . . . . . . . . . . . .

102Command Activity Document . . . . . . . . . . .

101How to Create a Command Activity . . . . . . .

101When to Use a Command Activity . . . . . . . .

101Introduction to the Command Activity . . . . .

1019 Command Activity . . . . . . . . . . . . .

Contents v

146Step 11: Save, Initialize Keys, and

Close the Document . . . . . . . . . . . . . .

146Step 10: Select Scheduling Options . . . . . .

145Step 9: Select Options . . . . . . . . . . . . . . . .

144Step 8: Enable Subforms . . . . . . . . . . . . .

143Step 7: Name the Activity Document . . . .

142Step 6: Select Events to Monitor . . . . . . . .

141Step 5: Map Key and Data Field(s) . . . . . .

139Step 4: Select the Lotus Connection

for the Data Source . . . . . . . . . . . . . . .

138Step 3: Select the Notes Form to

Monitor . . . . . . . . . . . . . . . . . . . . . . . .

137Step 2: Select the Domino Database . . . . .

136Step 1: Open the Activity Document . . . .

136Creating a Virtual Fields Activity Using

the User Assistant . . . . . . . . . . . . . . . .

134

Usage Requirements, Performance, andMapping in Virtual FieldsActivities . . . . . . . . . . . . . . . . . . . . . . .

131Introduction to Virtual Fields Activities . . . .

13112 Virtual Fields Activity . . . . . . . . .

128Considerations for Polling Activity

Scheduling . . . . . . . . . . . . . . . . . . . . .

128Error Handing Options . . . . . . . . . . . . . .

126Definition . . . . . . . . . . . . . . . . . . . . . . . .

124Connection . . . . . . . . . . . . . . . . . . . . . . .

124Identification . . . . . . . . . . . . . . . . . . . . . .

123Polling Activity Document . . . . . . . . . . . . . .

122How to Create a Polling Activity . . . . . . . . .

121When to Use the Polling Activity . . . . . . . . .

121Introduction to the Polling Activity . . . . . . .

12111 Polling Activity . . . . . . . . . . . . . . .

119Using Oracle or ODBC to Create

Target Metadata . . . . . . . . . . . . . . . . .

119Using the Lotus Connector for File

System . . . . . . . . . . . . . . . . . . . . . . . .

176Delete Options . . . . . . . . . . . . . . . . . . . . .

174Update Options . . . . . . . . . . . . . . . . . . . .

172Open Options . . . . . . . . . . . . . . . . . . . . .

170Create Options . . . . . . . . . . . . . . . . . . . .

169Event Options Create, Open, Update,

and Delete . . . . . . . . . . . . . . . . . . . . . .

167Creating a Virtual Attachments Table . . . .

163Virtual Attachments . . . . . . . . . . . . . . . .

161Integrated Credentials in Virtual

Fields . . . . . . . . . . . . . . . . . . . . . . . . .

158Multi-value Data in Virtual Fields . . . . . .

157Initialize Keys in Virtual Fields . . . . . . . .

153General Options in Virtual Fields . . . . . .

152Virtual Fields Activity Document

Options . . . . . . . . . . . . . . . . . . . . . . . .

151Step 11: Process the Virtual Fields

Activity . . . . . . . . . . . . . . . . . . . . . . . .

150Step 10: Save, Initialize Keys, and

Close the Document . . . . . . . . . . . . . .


150Step 8: Select Options and Event

Options . . . . . . . . . . . . . . . . . . . . . . . .

150Step 7: Select Event(s) to Monitor . . . . . . .

149Step 6: Mapping Key and Data Fields . . . .

148Step 5: Enable Subforms . . . . . . . . . . . . .



147

Step 3: Select the DominoApplication and the Form toMonitor . . . . . . . . . . . . . . . . . . . . . . . .

147Step 2: Enter a Name for the Activity . . . .


147Creating a Virtual Fields Activity

without the User Assistant . . . . . . . . .

147Step 12: Process the Virtual Fields

Activity . . . . . . . . . . . . . . . . . . . . . . . .

vi IBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide


202Step 8: Select Options . . . . . . . . . . . . . . . .


200Step 6: Create the External Key Table

(optional) . . . . . . . . . . . . . . . . . . . . . .

200Step 5: Map Data Field(s) . . . . . . . . . . . . .



197Step 3: Select the Notes Form to

Monitor . . . . . . . . . . . . . . . . . . . . . . . .

196Step 2: Select the Domino Database . . . . .


194Creating a Virtual Documents Activity

Using the User Assistant . . . . . . . . . . .

194Soft Deletions . . . . . . . . . . . . . . . . . . . . .

193Deletion Stubs . . . . . . . . . . . . . . . . . . . . .

193Special Considerations When Deleting

Virtual Documents . . . . . . . . . . . . . . .

192Special Considerations When Using

Public Key Encrypted Fields . . . . . . . .

191Indexing to Increase Performance . . . . . . . . .

189Using and Testing the Required

External System Fields . . . . . . . . . . . .

187Virtual Documents Required

Column Data Types . . . . . . . . . . . . . .

185Required External System Metadata for

Virtual Documents Activities . . . . . . .

184Virtualizing Preexisting Data . . . . . . . . . .

183Virtual Documents and Monitored

Forms . . . . . . . . . . . . . . . . . . . . . . . . .

179Comparing Virtual Documents and

Virtual Fields . . . . . . . . . . . . . . . . . . .

179Introduction to Virtual Documents

Activities . . . . . . . . . . . . . . . . . . . . . . .

17913 Virtual Documents Activity . . . .

178Running Virtual Agents Against Virtual

Fields . . . . . . . . . . . . . . . . . . . . . . . . .

229Using Stored Procedures in Virtual

Documents Events . . . . . . . . . . . . . . .

228Delete Options . . . . . . . . . . . . . . . . . . . . .

226Update Options . . . . . . . . . . . . . . . . . . . .

225Open Options . . . . . . . . . . . . . . . . . . . . .

223Create Options . . . . . . . . . . . . . . . . . . . .

223Event Options Tab . . . . . . . . . . . . . . . . . . . .

220Creating a Virtual Attachments Table . . . .

217Virtual Attachments . . . . . . . . . . . . . . . .

215Integrated Credentials . . . . . . . . . . . . . . .

209Creating an External Key Table . . . . . . . .

206General Options . . . . . . . . . . . . . . . . . . .

206Virtual Documents Options Tab . . . . . . . . . .

205Virtual Documents Activity Document

Options . . . . . . . . . . . . . . . . . . . . . . . .

205Step 10: Process the Virtual

Documents Activity . . . . . . . . . . . . . .

204Step 9: Save and Close the Document . . . .



Options . . . . . . . . . . . . . . . . . . . . . . . .

204Step 6: Create the External Key Table

(optional) . . . . . . . . . . . . . . . . . . . . . .

204Step 5: Mapping . . . . . . . . . . . . . . . . . . .



203

Step 3: Select the DominoApplication and the Form toMonitor . . . . . . . . . . . . . . . . . . . . . . . .



203Creating a Virtual Documents Activity


202Step 11: Process the Virtual

Documents Activity . . . . . . . . . . . . . .

202Step 10: Save and Close the

Document . . . . . . . . . . . . . . . . . . . . . .

Contents vii

246Virtual Agents Activity Document

Options . . . . . . . . . . . . . . . . . . . . . . . .

245Step 8: Process the Virtual Agents

Activity . . . . . . . . . . . . . . . . . . . . . . . .




Options . . . . . . . . . . . . . . . . . . . . . . . .



244Step 3: Select the Domino

Application to Monitor . . . . . . . . . . . .



244Creating a Virtual Agents Activity


244Step 9: Process the Virtual Agents

Activity . . . . . . . . . . . . . . . . . . . . . . . .




Options . . . . . . . . . . . . . . . . . . . . . . . .


242Step 4: Select the Owner . . . . . . . . . . . . . .


for the External Data Source . . . . . . . .

240Step 2: Select the Domino Database

to Monitor . . . . . . . . . . . . . . . . . . . . . .


238Creating a Virtual Agents Activity

Using the User Assistant . . . . . . . . . . .

238Stored Procedure Parameters . . . . . . . . . .

237Introduction to Virtual Agents Activities . . . .

23714 Virtual Agents Activity . . . . . . . .


Documents . . . . . . . . . . . . . . . . . . . . .

231Stored Procedure Examples . . . . . . . . . . .

279Introduction to the Java Activity . . . . . . . . . .

27916 Java Activity . . . . . . . . . . . . . . . . . .

278Skip Deletions . . . . . . . . . . . . . . . . . . . . .

277Skip Updates . . . . . . . . . . . . . . . . . . . . . .

276Skip Insertions . . . . . . . . . . . . . . . . . . . . .

276Replication Examples . . . . . . . . . . . . . . . . . .

274Using Restrictions in Timestamp

Replication . . . . . . . . . . . . . . . . . . . . .

273Using Restrictions in Keyed

Replication Activities . . . . . . . . . . . . .

270Using the Do Not Replicate Timestamp

Option . . . . . . . . . . . . . . . . . . . . . . . .

263Replication Options . . . . . . . . . . . . . . . . .

261Mapping . . . . . . . . . . . . . . . . . . . . . . . . .

259Identification . . . . . . . . . . . . . . . . . . . . . .

259Special Settings . . . . . . . . . . . . . . . . . . . .

258Replication Activity Document . . . . . . . . . . .

257How to Create a Replication Activity . . . . . .

256Sort Order Considerations . . . . . . . . . . . .

256Specifying a Selection View in a

Notes Database . . . . . . . . . . . . . . . . . .

256Using Database Triggers with

Timestamp Replication . . . . . . . . . . . .

252Types of Replication Activities . . . . . . . . .

251When to Use the Replication Activity . . . .

251Introduction to the Replication Activity . . . .

25115 Replication Activity . . . . . . . . . . .


Fields . . . . . . . . . . . . . . . . . . . . . . . . .


Documents . . . . . . . . . . . . . . . . . . . . .

249Executing Virtual Agents from HTTP

Client . . . . . . . . . . . . . . . . . . . . . . . . .

248Integrated Credentials in Virtual

Agents . . . . . . . . . . . . . . . . . . . . . . . .

246General Options in Virtual Agents . . . . . .

viii IBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide

397Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

393Appendix E Using VirtualActivities in a Domino Cluster . . . .

377Appendix D Using VirtualFields with Virtual Documents . . . .

321Appendix C Tutorials . . . . . . . . . . . .

297Appendix B Error Messagesand Troubleshooting . . . . . . . . . . . . .

293Appendix A LEI and Data . . . . . . . .

291Scripted Activity Considerations . . . . . . . . .

290Determining if an Agent is Running . . . .

288Agent Development Document . . . . . . . .

288Script . . . . . . . . . . . . . . . . . . . . . . . . . . . .

287Identification . . . . . . . . . . . . . . . . . . . . . .

286Scripted Activity Document . . . . . . . . . . . . .

286How to Create a Scripted Activity . . . . . . . .

285Running Unrestricted LotusScript

Agents . . . . . . . . . . . . . . . . . . . . . . . .

285How LEI Supports LotusScript . . . . . . . . . . .

283Introduction to the Scripted Activity . . . . . .

28317 Scripted Activity . . . . . . . . . . . . . .

281Java . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

281Identification . . . . . . . . . . . . . . . . . . . . . .

280Java Activity Document . . . . . . . . . . . . . . . .

279How to Create a Java Activity . . . . . . . . . . .

279When to Use the Java Activity . . . . . . . . .

Contents ix

Preface

This document provides information about IBM Lotus Enterprise Integratorfor Domino (LEI). It describes how to use the LEI server and LEI Adminis-trator. It also describes each LEI Activity. Tutorials are available in the lastappendix.

Information about Lotus Connectors and connectivity is described in thecompanion document entitled Lotus Connectors and Connectivity Guide(lccon6.nsf). This documentation file is installed with Domino, not with LEI.The lccon6.pdf file is available for download at http://www.notes.net.

Related DocumentationThis section lists documentation that you may find useful as you learnabout and use LEI.

Note Two of the four LEI user documentation files (Lotus Connectors andConnectivity Guide - lccon6.nsf and Lotus Connector LotusScript ExtensionsGuide - lsxlc6.nsf) are also part of the DECS documentation set and are nowsupplied with Domino only, not LEI. To obtain these two neededdocumentation databases, you must either install DECS or perform acustom install of the Domino server and select the DECS User Assistanceoption. These two files are also available at http://www.notes.net. TheirPDF equivalents are available only at http://www.notes.net.

LEI Documentation SetDocumentation for LEI is available online with the product distribution andat http://www.notes.net. The LEI documentation set is listed below:

• IBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide— Provides information and instructions for using LEI and its Activities(leidoc.nsf and leidoc.pdf).

• IBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide —Provides installation, configuration, and migration instructions for LEI(leiig.nsf and leiig.pdf).

• Lotus Connectors and Connectivity Guide — Provides information on howto set up and use the supplied Lotus Connectors, including informationabout required software and instructions for testing connectivity(lccon6.nsf). This documentation file is installed with Domino, not withLEI. The lccon6.pdf file is available for download athttp://www.notes.net.

xi

• Lotus Connector LotusScript Extensions Guide — Describes the LotusConnector LotusScript Extensions, which can be used in writingscripted sessions for accessing enterprise data (lsxlc6.nsf). Thisdocumentation file is installed with Domino, not with LEI. Thelsxlc6.pdf file is available for download at http://www.notes.net.

• IBM Lotus Enterprise Integrator for Domino (LEI) Release Notes — Therelease notes (readme.txt) contain information about the current releaseof LEI that may not be included in the documentation set.

Current information about LEI can also be found at http://www.lotus.com/ei.

Other DocumentationFor more information about related tools, refer to the following documents:

• Domino Administrator’s Guide — This manual provides information forconfiguring and administering a Notes installation.

• LotusScript Language Reference — This manual provides informationabout writing LotusScript programs. This could be useful if you want touse the Domino LotusScript Extensions (LSX) to write customActivities.

• Additional Lotus Connector Documentation — Lotus Software, IBMSoftware Group sells additional Lotus Connectors for enterprisesystems including Enterprise Resource Planning (ERP) and TransactionProcessing Systems. Specific documentation about those Connectors isincluded with the specific Connector software and package. You mayneed documentation for the specific databases, ERP, or transactionprocessing systems that you are using.

Contact and Support InformationLotus Software, IBM Software Group provides extensive support for itsproducts.

Enterprise Integrator Web SiteTo obtain the latest information about LEI and DECS, visit the followingWeb site:

http://www.lotus.com/ei

Note Domino-related product updates for iSeries can be found atfollowing Web site:

http://www-1.ibm.com/servers/eserver/iseries/domino/support/qmu.htm

Technical SupportTo contact Customer Support with suggestions or questions regarding yourLotus Connector or LEI/DECS application, call 1-800-346-6388.

xii IBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide

Chapter 1 Introduction

This chapter provides information about the organization of this manualand terms you should know when working with IBM Lotus EnterpriseIntegrator for Domino (LEI). This chapter also includes an overview of LEI,including a description of its features, functionality, and architecture.

Organization of this ManualThis manual includes the sections described in the following table.

continued

This chapter provides information about the ArchiveActivity.

Chapter 8Archive Activity

This chapter provides information about the AdminPurge Log Activity.

Chapter 7Admin Purge Log Activity

This chapter provides information about the AdminBackup Activity.

Chapter 6Admin Backup Activity

This chapter introduces LEI Activities. It includesdescriptions of items that are common to allActivities, and provides basic information forworking with Activity documents.

Chapter 5Introduction to LEIActivities

This chapter points to the companion manual LotusConnectors and Connectivity Guide.

Chapter 4Introduction to Connectors

This chapter provides an introduction to the LEIAdministrator and information on using it.

Chapter 3LEI Administrator

This chapter provides information about starting theLEI server and using the server commands. Alsoincluded are instructions for configuring the LEIserver to automatically start at system startup.

Chapter 2Starting and Running theLEI Server

This chapter provides information about theorganization of this manual and terms you shouldknow when working with LEI. This chapter alsoincludes an introduction to LEI, with an overview ofthe architecture. It also states how to contact Lotus.

Chapter 1Introduction

DescriptionSection

1

This appendix contains practical considerations whenusing the LEI Advanced RealTime Activities in aDomino cluster.

Appendix EUsing Virtual Activities in aDomino Cluster

This appendix provides insight into using the VirtualFields Activity in conjunction with the VirtualDocuments Activity.

Appendix DUsing Virtual Fields withVirtual Documents

This appendix contains tutorials for creating LEIActivities.

Appendix CTutorials

This appendix contains information abouttroubleshooting LEI.

Appendix BError Messages andTroubleshooting

This appendix contains information about how LEImaps data types between different applications.

Appendix ALEI and Data

This chapter provides information about the ScriptedActivity.

Chapter 17Scripted Activity

This chapter provides information about the JavaActivity.

Chapter 16Java Activity

This chapter provides information about theReplication Activity.

Chapter 15Replication Activity

This chapter provides information about the VirtualAgents Activity. This is one of three LEI AdvancedRealTime Activities.

Chapter 14Virtual Agents Activity

This chapter provides information about the VirtualDocuments Activity. This is one of three LEIAdvanced RealTime Activities.

Chapter 13Virtual Documents Activity

This chapter provides information about the VirtualFields Activity. This is one of three LEI AdvancedRealTime Activities.

Chapter 12Virtual Fields Activity

This chapter provides information about the PollingActivity.

Chapter 11Polling Activity

This chapter provides information about the DirectTransfer Activity.

Chapter 10Direct Transfer Activity

This chapter provides information about theCommand Activity.

Chapter 9Command Activity

DescriptionSection

Note The Character Sets appendix from the LEI Release 3.2 documentationhas been moved to the Lotus Connector LotusScript Extensions Guide lsxlc6.nsfsupplied with Domino and located also at http://www.notes.net.

2 IBM Lotus Enterprise Integrator for Domino (LEI) Activities and User Guide

Getting Started with LEIThe steps below summarize how to get started with LEI.

1. Install LEI. See the IBM Lotus Enterprise Integrator for Domino (LEI)Installation Guide.

For installation and configuration issues, see the IBM Lotus EnterpriseIntegrator for Domino (LEI) Installation Guide. Also see “Introduction toLEI,” in this chapter, and also the Troubleshooting appendix in thisdocument.

If upgrading and migrating from DECS or LEI Release 3.n, also see theMigration chapter in the IBM Lotus Enterprise Integrator for Domino (LEI)Installation Guide.

2. Establish and test database connectivity. See the Lotus Connectors andConnectivity Guide.

3. Start the LEI server. See the chapter entitled “Starting and Running theLEI Server.”

4. Build connections for each external data source. See the Lotus Connectorsand Connectivity Guide.

5. Build activities. See the chapter that describes the type of activity youwant to create. Also see the chapter entitled “Introduction to LEIActivities.”

6. Schedule and run activities. See the chapter that describes the type ofactivity you want to create. Also see the chapter entitled “Introductionto LEI Activities.”

7. In case of difficulties, see the Troubleshooting appendix.

8. For practice examples, see the Tutorials appendix.

Introduction to LEIIBM Lotus Enterprise Integrator for Domino (LEI) is an enterprise integra-tion tool that moves data between disparate external data sources.

LEI ArchitectureLEI is a data distribution application designed to enable enterprise-widedata access across multiple platforms. It is comprised of two maincomponents:

• LEI Server

• LEI Administrator

Chapter 1: Introduction 3

OverviewThe figure below illustrates the components of the LEI architecture andshows how data is processed by LEI. The LEI Administrator is used toadminister the configuration and operational elements of the LEI system,including Connectors, Metaconnectors, and Activities. The LEI serverperiodically polls the LEI Administrator database for Activities to execute.When it finds an Activity that is scheduled to run, it executes that Activity.An Activity defines the actions that the LEI server will perform, such astransfer of data, replication of data, file system commands and so on.

Each component is described in more detail in the sections below.


LEI ServerThe LEI server is an engine that polls the LEI Administrator database (alsoreferred to as the Control Store) for instructions to execute. These instruc-tions are in the form of LEI Activities.

Activities can be declarative or scripted. Declarative Activities are forms-based Activities created with the LEI Administrator. Scripted Activities arewritten in LotusScript, using the Lotus Connector LSX with LEI LotusScriptExtensions.

Once an Activity is written, it can be run from the Administrator or fromthe operating system command line.

The LEI server runs as a multithreaded, multiprocessing task on serveroperating systems. It performs the actual work in transferring data betweenexternal sources, such as between Oracle and Sybase or between SAP andNotes, etc.

The LEI server is described in the chapter entitled “Starting and Runningthe LEI Server.”

Note Client libraries of the external systems to be accessed must beinstalled on the LEI server and the Domino server. When running activities,if the LEI server that you want the activity to run on, and the Dominoserver where the LEI Administrator resides are on separate machines, theclient libraries must be installed on both machines.

LEI AdministratorThe LEI Administrator is a Notes application that enables users to createConnections and Activities. It uses a variety of forms and documents,including:

• Configuration

• Connections

• Metaconnections

• Activities

See subsequent sections for more information about each of these items.

The LEI Administrator is described in the chapter entitled “LEI Administra-tor.”


Lotus ConnectorsLotus Connectors provide connectivity to external data sources. ConnectionDocuments specify the names and network locations of each source. Use theLEI Administrator form specific to the type of connection you want tobuild. LEI provides Lotus Connectors for the following data sources:

• Notes

• DB2

• File System

• Open Database Connectivity (ODBC)

• Oracle 7

• Oracle 8

• OLE DB

• Sybase

• Text

Before building connections, verify connectivity using the communicationssoftware appropriate to the specific data source. For more informationabout establishing and testing connectivity, refer to the Lotus Connectors andConnectivity Guide.

For iSeries users, check with your system administrator to determine whatLotus Connectors are available.

Connection options enable you to modify operational aspects of specificconnections. They appear as fields within the Connection Document. Forinformation about building connections, refer to the Lotus Connectors andConnectivity Guide.

A Metaconnector is a special LEI Connector. A metaconnection “wrapsaround” a base connection, appearing to the Activity like the base connec-tion but providing additional functionality. LEI provides the followingMetaconnectors:

• Order — The Order Metaconnector can be used to obtain a consistentordering of results. For example, dictating a common ordering schemebetween EBCDIC and ASCII server data, resulting in accuratereplication and data evaluation operations. The Order Metaconnectionorders the result set based on user-defined criteria.


• Collapse/Expand — The Collapse/Expand Metaconnector collapsesmultiple records with a common key value into a single record withmulti-value fields, or expands multi-value fields into multiple records.It can be used to transfer multiple source records to a single targetrecord, or vice versa. It collapses records on fetch operations, andexpands them on write operations according to user-defined criteria.

• Meter — The Meter Metaconnector measures data access rates andvolumes and provides other statistical information.

• Trace — The Trace Metaconnector enables you to capture trace data.Options exist for specifying a timestamp, where to capture trace data,and what file name to use for logging output. This Metaconnection isusually used in a customer support-assisted situation.

Note Metaconnectors add an additional level of functionality.Metaconnector functionality is included in the Advanced RealTimeActivities. For other LEI Activities, they are defined in a separateConnection Document.

Metaconnectors are described fully in the companion document LotusConnectors and Connectivity Guide.

LEI ActivitiesActivities are the core of LEI. An LEI Activity tells the LEI server what to doand when to do it. You define Activities using the LEI Administrator.

Specific types of LEI Activities are listed below:

• Admin Backup Activity — Provides a way to schedule and executeregular backups of your LEI Administrator databases.

• Admin Purge Logs Activity — Provides a way to schedule and executethe purging of LEI logs.

• Archive Activity — Provides a way to schedule and execute regulararchiving of your databases.

• Command Activity — Enables execution of operating system anddatabase commands.

• Direct Transfer Activity — Allows you to transfer data between asource and target database by specifying SQL queries, Notes formulasor other data source-specific commands.

• Java Activity — Provides a way to schedule and execute Java programswith the LEI server.


• Polling Activity — Allows you to monitor data sources for specifiedconditions. When a condition is met, LEI immediately executes one ormore specified activities.

• Advanced RealTime Activities — Enables a Notes form for real-timeinteractive access with external system data. The Advanced RealTimeActivities are Virtual Fields, Virtual Documents, and Virtual Agents.

• Replication Activity — Enables data synchronization betweendissimilar databases.

• Scripted Activity — In addition to the standard declarative Activitiesthat can be defined using the LEI Administrator, LEI also providesLotusScript Extensions that can be used to create scripted activities.This enables you to develop more advanced Activities that can performdata manipulation and data massaging. For more information, see theLotus Connector LotusScript Extensions Guide.

Each LEI Activity is described in its own chapter in this manual.

LEI LogsLEI maintains a system log database that tracks system performance. Theselogs are helpful in assessing the performance of specific Activities, and areuseful for troubleshooting. LEI maintains three types of logs:

• Activity Logs — These track individual Activities and provideperformance statistics.

• Operation Logs — These track any errors encountered when running anActivity.

• Server Logs — These track the operation and performance of LEIservers.

In any activity view, you can see the log display for the most recent run ofthat activity using the Log action button.

LEI logs are described in more detail in the chapter entitled “LEI Adminis-trator.”


Obtaining Help and Opening User DocumentationAll Activity Documents and Connection Documents are supplied withpop-up help and field-level help incorporated into the user interface. Onlinemanuals are also available in .nsf form from the LEI Administrator Navigatorand in .pdf form as supplied with LEI and also at http://www.notes.net.

User Assistant HelpYou can optionally enable the User Assistant to assist you in creating anAdvanced RealTime Activity or in creating or editing a ConnectionDocument. The User Assistant prompts you the through the creation of anew Advanced RealTime Activity. With the User Assistant enabled, newand existing Connection Documents open with explanatory text at the topof the document. You can toggle the User Assistant on and off using theHelp option in the Navigator panel of the Administrator.

Pop-up HelpEvery LEI Activity Document and Connection Document includes pop-uphelp for each of the sections and most of the fields. This help is designed tomake the requirements for the associated field easier to understand. Darkblue text indicates that pop-up help is available. To display pop-up help fora particular user interface option, position your cursor on the option andpress any mouse button. Pop-up help appears immediately.

Field-level HelpField-level help is available for all editable fields. It is provided in thebottom area of the user interface. To display field-level help, you must be inEdit mode. Once you are in Edit mode, field-level help appears when youposition the cursor on any field where user input is accepted. Field-levelhelp describes action options for each field on the Activity Document orConnection Document.

User DocumentationThe LEI documentation set is comprised of four manuals as described in thepreface of this document. The manuals are supplied in .nsf and .pdf format.To open a particular manual in .nsf format, click the Help option on the LEIAdministrator and select one of the resultant four title choices. Once themanual is open, use its table of contents of topic choices to quickly navigateto the needed information. LEI user documentation is also available at theLotus Developer Domain (LDD) at http://www.notes.net.


General LEI TermsBecause LEI works with several database products, directories, ERPsystems, and transaction processing systems, it’s important to understandthe vocabulary used in LEI and in other data sources.

continued

A packaged set of operations in an external system.Procedures (also called Stored Procedures or RemoteProcedure Calls) are executed to produce a result set,modify external data, or perform some other action.Procedures obtain input data through parameters andreturn data either through output parameters or returnedresult sets.

Procedure

Parameters are used to pass data or other information to orfrom procedures.

Parameter

Metadata describes the types, names, and collections ofdata within a database.

Metadata

A collection of key values enabling rapid searches. InDomino, a View is an index.

Index

The standard metadata object in Notes. A form defines thefields and data type used to create and display documentsin a Domino database.

Form

In LEI, the metadata description or data for one element ofa record. Each record contains one or more fields, eachwith a data type, data value and other properties.

Field

Referred to in LEI as a record. A Notes document is adatabase entry that contains data. It is the equivalent of adatabase row and appears in row format in a Notes View.

Document

A collection of metadata and data. A Lotus Dominodatabase is stored as a file with the extension .nsf. Othersystems generally abstract the database from the filesystem.

Database

Referred to as a field in LEI, a set of similar data such asphone numbers or customer names. Usually displayed incolumn format, such as in a Notes View.

Column

DescriptionTerm


In Domino, a View collates and displays a list ofdocuments with selected fields and acts as an index tothose documents.

In relational databases, a view is a customizedpresentation of data from one or more tables.

View

Referred to in LEI as metadata. A set of data in a relationaldatabase stored as rows and columns.

Table

A statement in a system’s native language syntax.Statements can produce result sets (selection statements) orinvoke modifications, commands, or procedures. Examplesinclude a Notes formula or SQL query.

Statement

In a relational database, the equivalent of a record.Row

The set of data (rows or records) resulting from a selectionoperation. For example, the data to be transferred afterbeing selected through a Notes selection statement or aSQL query would be a result set.

Result set

An element of data composed of one or more fields.Examples are a row in a relational database or a documentin Notes.

Record

DescriptionTerm

AccessibilityAccessibility features help a user who has a physical disability, such asrestricted mobility or limited vision, to use software products successfully.LEI adheres to the IBM and Lotus Notes Accessibility guidelines. Seehttp://www-3.ibm.com/able/guidelines.htm for more information onAccessibility.

LEI provides keyboard access as an alternative or to augment its graphicaluser interface.

The main LEI Navigation screen is a series of frames on a frameset. Tonavigate from one frame to another, press the <F6> key to move down andright or Shift <F6> to move up and left. Action buttons may be accessed bypressing the <Alt> key while in a frame and pressing the number displayedon the button.


Note As an alternative to the Add Connection and Add Activity actionbuttons on the LEI Administrator, you can select the Create button in thetop bar to yield the following pulldown menu.

Once you open a Connection Document or Activity Document, you canpress the tab key or the <Ctrl>E keys to enter Edit mode. You can tab fromone document field to another. You can also use the arrow keys to move thecursor and change focus. You can use the Return key to select an action,such as toggling a document option on or off.

Note When you are in Edit mode, field level help displays automaticallyfor whatever field has focus. Field help appears at the bottom of the userinterface. Pop-up help is also available for all dark blue ConnectionDocument and Activity Document options using the mouse, but pop-uphelp is not available from the keyboard.

To simplify user interaction with the application, LEI supports the shortcutkeys listed next to the menu options on the top bar, such as File, Edit, View,and so on. To use the keyboard to open a top bar menu and then displayhelp on any of its content, press <Alt> and the underlined character (forexample, F for File, E for Edit). Keyboard equivalents are listed to the rightof all pulldown menu choices.

You can use screen-reader software and a digital speech synthesizer to hearwhat is displayed on the screen. You can also use voice recognitionsoftware, such as IBM ViaVoice, to enter data and to navigate the user inter-face.


PerformanceThis section contains useful configuration tips for obtaining the best LEIperformance. For performance considerations that are specific to LEIAdvanced RealTime activities, see the Virtual Documents, Virtual Fields,and Virtual Agents chapters later in this guide.

Sample LEI Configuration with Processing TimesThis section contains parameters and processing times for a sample Replica-tion Activity and Direct Transfer Activity using the supplied sampledatabase leiempsamp.nsf. Data transfer was done across a network. In thissample configuration, the following parameters were present:

• Platform and OS = Windows NT SP6a

• Domino Server running Domino R6

• LEI Release 6 Server

• RAM total = 163,248K

• RAM available = 56,560K

• Hard drive = 4GB

• Free Space = 3GB

• pagefile.sys = 163,840K (160MB)

Using this test scenario, the Replication Activity with “Log Conflicts On”enabled and a 10,000 record database with conflicts will complete in 1-5minutes depending on your external system and connection choice.

Using this test scenario, the Direct Transfer Activity and a 10,000 recorddatabase will complete in 0.5-3 minutes depending on your external systemand connection choice.


General Performance Considerations

• Array Transfer

Array transfer, also known as bulk transfer, is a term used to describethe ability of a Connector to transfer many records at once. The benefitof transferring many records at once is that only one networktransaction is needed, rather than many, for a given set of records.Using array transfer, the data has the same number of bytes but thetransfer takes less time. Array transfers can be used for read (fetch) orwrite (insert) operations, depending on the RDBMS and the Connector.

The Performance section of the Direct Transfer Activity documentcontains options that pertain to array transfer. The Lotus Connector forNotes and Lotus Connector for DB2 support array transfer for insertoperations. The Lotus Connector for Oracle 7 supports array transferfor fetch and insert operations. The other Lotus Connectors do notsupport array transfer.

• Creating Indexes for RDBMS

A writeback index, also known as a database index, can accelerate LEIperformance for RDBMS that support writeback. A writeback indexenables writeback support for a given metadata object. SomeConnectors require that a unique index exist, while others do not.

The “Create Connection A Metadata” and “Index to create on MetadataCreation” options on the Replication Activity document pertain toindex creation. The index created is used by LEI when performing datacomparisons during replication. An index is crucial for goodperformance against some Connectors, such as relational databases.

The Lotus Connectors that support a writeback index are Notes, DB2,ODBC, Oracle 7, Oracle 8, and Sybase.

• Refresh Database

Some Connectors and Activities support automatic or requesteddatabase refresh. Database refresh reflects the database changes in thedatabase views at the end of the transfer or replication process whenthe destination database is being closed. Since views can be slow tore-compute following many changes, enabling this option is notadvised. If enabled, the transaction must wait to complete until thedatabase is completely regenerated. It also causes the refresh to occur aspart of the transfer rather than when you next open the view. The nexttask can’t start until the transaction is complete and the database isregenerated. Enabling database refresh increases transaction timessignificantly, thus slowing down processing performance.


Advanced RealTime Activity: Indexing Increases PerformanceHigh performance is crucial for the Advanced RealTime Activities, sincethey may be serving many clients. Performance can be increased by index-ing fields on the external system. This is true for both Virtual Documentsand Virtual Fields.

The following two sections bullets discuss the benefits of indexing fields toincrease performance. However, more detailed information can be found inthe Virtual Documents activities chapter of this guide.

• Performance in Virtual Documents Activities and Virtual DocumentsUsing Virtual Attachments

It is critical to the performance of the Virtual Documents Activities tobuild indexes on the external system server.

See “Required External System Fields for Virtual Documents Activities”and “Usage Requirements for Virtual Documents and VirtualAttachments” in the “Virtual Documents Activities” chapter, forcomplete information on the issue of indexing when you use VirtualDocuments activities.

If you are using Virtual Attachments with Virtual Documents, certainfields in the Virtual Attachment Table should be indexed. Forinformation concerning indexing Virtual Attachments fields when usedwith Virtual Documents, see “Virtual Attachments in VirtualDocuments” in the “Virtual Documents Activities” chapter.

• Performance in Virtual Fields

To maximize performance in Virtual Fields Activities, when theexternal Connector is an SQL database, make sure an SQL index existson the key fields. For more information, see “Usage Requirements andPerformance in Virtual Fields Activities” in the “Virtual FieldsActivities” chapter.

Using Advanced RealTime Activities in a Clustered Domino ServerEnvironment

Advanced RealTime Activities can be used to great advantage in a clusteredDomino server environment. See Chapter 1 of the IBM Lotus EnterpriseIntegrator for Domino (LEI) Installation Guide for complete information.


Web-based Application ConsiderationsIf you are using a Web-based application and programmatically connectingto a database that supports synchronous or asynchronous data transfers(such as DB2 or Oracle), set the data transfer method to be asynchronous.

LEI on the iSeriesThis section provides information about LEI specific to its use and imple-mentation on the iSeries platform.

LEI Server on iSeriesOn iSeries, the LEI server is a 64-bit application which will execute as anaddin server task to a native 64-bit Domino server on iSeries. Access to DB2databases, Notes databases and File System objects is allowed via the LEIserver running on iSeries. Direct (native API) Connections to databases suchas Oracle and Sybase are not supported on iSeries, nor is the ODBC Connec-tion allowed. Access to non-DB2 data sources can be achieved by using theIBM DataJoiner product on an NT IPCS server, outboard NT, or AIXplatform to reroute DRDA requests from iSeries to the target data source.Connections to Sybase, Oracle and other ODBC accessible databases can,however, be registered in an administration database for LEI servers config-ured to run on non-iSeries platforms in your LEI cluster.

LEI Server Running Window on iSeriesUnlike other LEI platforms, iSeries does not have an LEI server window orconsole. The running state of LEI can be viewed from the LEI administra-tion database or from the Domino console on iSeries (through Show Tasks).The LEI server is an addin task to iSeries Domino server and so it is notlaunched in its own interactive process or window. Commands (such asShutdown Server, Stop Server, Close Activity, and Kill Activity) that can beissued in the server window on other server platforms are available fromthe Action menu of the LEI Administrator or the Domino console. TheReconfigure option is automatic. When the LEI server configurationdocument is changed, the corresponding server will reconfigure during itsnext polling cycle or when the server is restarted, whichever happens first.


Languages Support on iSeriesLEI is considered an administrative tool and is therefore currently availablein English only. The LEI user interface is available in English only. TheEnglish language (2924) does not have to be installed on your iSeries.

Code Page Translation Support on iSeriesData translation is automatic (not optional) for LEI on iSeries becauseiSeries uses EBCDIC character sets. This is incompatible with Domino’s useof the LMBCS character set. LEI supports data translation in a variety oflanguage code pages.

LEI Activities launched under the LEI server will default to the job CCSIDof the Domino server. See iSeries Domino server documentation for how toset the default job CCSID (the locale information specified in the QNOTESuser profile) for Domino server addins.

All LEI Activity functions are supported for iSeries.

The following Lotus Connectors and Metaconnectors are supported foriSeries:

• Connectors: DB2, Notes, File, Text

• Metaconnectors: Collapse/Expand, Meter, Order, Trace

Term Comparison for iSeriesThe following table compares key terms that you will find in this manual.

Selection formulaQuery n/aStatement

FieldColumnFieldField

Document RowRecordRecord

FormTableFile Metadata

Database (.nsf file)DatabaseAny RDB registered viaWRKRDBDIRE, including thelocal DB2/400 database

Database

NotesSQLiSeries Relational DBTerm


Chapter 2 Starting and Running the LEI Server

This chapter provides information and instructions for starting and runningthe LEI server on the supported operating systems.

Starting the LEI ServerThe LEI server must be running in order to execute LEI Activities.

Start the LEI server by executing the LEI program at the LEI servermachine. The LEI program name varies by platform.

leiiSeries

leisSolaris

leiAIX

nlei.exeWin32

NamePlatform

On Windows, you can also start the LEI server by selecting it from thecorrect program group folder using the Start menu.

The LEI console appears, displaying the LEI server commands.

When started, the LEI server connects to the LEI Administrator databaseand immediately runs any overdue Activities. It continues to poll the LEIAdministrator at the interval defined in the server configuration documentand to run scheduled Activities until shut down.

19

Executing LEI Server Commands From the ConsoleThe following LEI server commands can be executed from the serverconsole window. The LEI server console commands are described below.

Shuts down the LEI server and all LEI Activities.Quit

Displays basic configuration information about this LEI server, aswell as server time and status.

Status

Displays a list of Activities that are currently being executed by thisLEI server. The number associated with each Activity name mustbe used with the Close and Kill commands.

List

Displays a brief description of the LEI server commands.Help

DescriptionCommand

Note When issuing commands in the LEI console, the command text islimited to 255 characters.

Additional Activity and server control options are available on the Actionsmenu using the LEI Administrator under the LEI Server Administrationand Activity Administration menus. See the “Executing LEI ServerCommands from the Administrator” section in this chapter for moreinformation.

Executing LEI Server Commands from the AdministratorThe following LEI server commands can also be executed from within theLEI Administrator.

• Close Activity

• Kill Activity

• Shutdown Server

• Stop Server

To close or kill an activity, choose Actions — Activity Administration, andchoose either Kill Activity or Close Activity.

To shutdown or stop the server, choose Actions — LEI Server Administra-tion and choose either Shutdown Server or Stop Server.

In either case, if an inappropriate document is selected when the action isattempted, an error message appears. If you receive an error message, seethe Error Messages and Troubleshooting appendix.


Running LEI as a Domino Addin TaskYou can run LEI as a Domino server addin task. This option is availablewhen you install LEI on Win32 and UNIX. LEI on the iSeries is installed as aDomino addin task.

This method automatically starts LEI when the Domino server starts andshuts down LEI as the Domino server is stopping. If you did not select thisoption during install, you can enable it manually by editing the Dominoserver’s notes.ini file and adding the task “lei” to the ServerTask list.

LEI can also be manually controlled as an addin task.

Note When used as a Domino addin, LEI converts all date/times to USformat on the Domino console.

Note If the Domino server starts as an NT service, to avoid sequencingproblems LEI should be added as a Domino server addin task. This willensure that Domino will start before there is an attempt to start LEI.

To start LEI as an addin manually, enter the following command from theDomino server console:

load lei addin

To manually shut down LEI when running as an addin task, enter thefollowing command from the Domino server console.

tell lei quit

When running as an addin task, the LEI console display is suppressed. Tosend LEI console commands, type the following command in the Dominoserver console:

tell lei <command>

For example, the following command will have the same effect as entering“l” at the standard LEI server console:

tell lei l

ConsiderationsWhen a Notes/Domino server is started as an NT service, Notes/Dominousers cannot access database/directory links that are at locations other thanthe local NT server. Applications installed as a service begin executionbefore the user is prompted to log in at the NT server. Therefore, whenNotes/Domino starts up as an installed service, any mapped drives that theNT server may have set up are not yet reconnected at the point when theNotes/Domino server is started. The Notes/Domino server only recognizesdrives that are available when it is first started. Drives that are mappedafter the Notes/Domino server has started are not recognized. In this

Chapter 2: Starting and Running the LEI Server 21

scenario, directory/database links that point to mapped drives on othercomputers will not function properly if the Notes/Domino server is startedas a service.

The solution for this set of circumstances is to not install Notes/Domino asa service. When Notes/Domino is not installed as a service, but rather ismanually initiated from either the Start Menu or a desktop shortcut, youmust be physically logged in at the NT server. Because you must log in atthe server, all network drive mappings will have been established when theNotes/Domino server is launched. Using this method, directory/databaselinks that are beyond the local server will function correctly.

Understanding the leiclean Script for UNIX and iSeriesThe leiclean program is provided with LEI installations on UNIX andiSeries platforms to clean up LEI resources following an abnormal termina-tion of LEI.

• UNIXleiclean

• iSeriescall Qnotes/leiclean

Use the leiclean program with caution. It kills all LEI processes owned bythe user who executes it. It also frees all shared memory and semaphorescurrently in use by that user. The removal of shared memory andsemaphores could affect other programs that are running under the sameuser ID, including the Domino server and any other Notes API programs.

If you execute LEI and the Domino server under the same user ID (as youmust to use Advanced RealTime), an abnormal termination by eitherprocess may halt the other. This is a Notes API limitation.

For Unix users, in addition to leiclean, there is a shell script that can be usedto clean up Notes/Domino processes after an abnormal termination. To usethis, change your directory to the Notes data directory and then execute thefollowing:

nsd -kill


Starting and Running the LEI Server on iSeriesThere are two ways of starting the LEI server after it is installed: automati-cally or manually.

Starting the LEI Server AutomaticallyWhen you install LEI on iSeries, the notes.ini file is automatically updatedto configure LEI as a Domino addin task using the ServerTask environmentvariable. Configuring LEI as a standalone is not supported on iSeries.

Starting the LEI Server ManuallyIf you close the LEI server process by issuing the command “tell lei quit”,from the Domino console, you can restart the LEI server manually using theWork Domino Console (WRKDOMCSL) command. For example, to workwith the console for a Domino server called LEISERVER1, you would enterthe following at the Domono console command line:

WRKDOMCSL LEISERVER1

From the console, you can also the following Notes command to start theLEI server:

LOAD LEI

Note With either method, if the LEI Administrator database (decsadm.nsf)resides on a different Domino server, that server must be active before LEIwill start.

Stopping the LEI Server on iSeriesThere are three ways to stop the LEI server.

• From the Domino console

• From the LEI Administrator

• By stopping the Domino server

From the Domino ConsoleFrom the Domino console, you can end the LEI server by issuing the follow-ing command.

tell lei quit

If you have LEI Activities currently running, they will end as soon as theyare notified of the quit request. The Activities will not run to completion.


From the LEI AdministratorYou have two options from the LEI Administrator using the *RUNNINGview:

• Shutdown — Ends LEI in an orderly fashion; Activities run tocompletion

• Stop — Ends LEI immediately; Activities do not run to completion

By stopping the Domino ServerBy issuing an ENDDOMSVR server name command, the LEI server willalso end in a controlled manner.

If you have LEI Activities currently running, they will end as soon as theyare notified of the server stopping. The Activities will not run tocompletion.

If you stop the Domino server using the *IMMED option, the jobs endimmediately and any LEI Activities currently active are terminated. Thiscan cause unexpected results, such as incomplete transfers or lengthyrollbacks. You should only use the *IMMED option if all other methods,including *CNTRLD, fail.

Determining if LEI Server is Running on iSeriesThere are three ways to determine if your iSeries LEI server is running.

• Show Task from Domino Console

• WRKACTJOB on iSeries

• From LEI Administrator Database

Show Task from Domino Console

• WRKDOMCSL domino-server-name

• show tasks

• F5 — REFRESH

The following tasks may display the activity name in the description.

• LEI server — Administrator is running

• LEI server — Server is running

• LEI server — Activity Transfer Daily Issues is running


WRKACTJOB on iSeriesWhen you enter the command WRKACTJOB, you will see the following LEIjobs under the subsystem for the Domino server. If Activities are running,there will be an LEIACT job running for each running Activity.

DOMINOxx

. . .

. . .

LEICSM

LEI

From LEI Administrator DatabaseSelect the *RUNNING view and look at the active server to see the list.


Chapter 3 LEI Administrator

This chapter introduces the LEI Administrator and describes its usage.

LEI AdministratorThe LEI Administrator is a Notes application. The LEI Administratordatabase (decsadm.nsf) contains all of the configuration, activity,connection, and scheduling elements that LEI servers use to collect, transfer,and write data. Additional information about the LEI Administrator can befound in the IBM Lotus Enterprise Integrator for Domino (LEI) InstallationGuide (leiig.nsf and leiig.pdf supplied with LEI and also athttp://www.notes.net).

The LEI Administrator interface is shown in the figure below. TheNavigator is shown on the left.

The LEI Administrator enables you to view, create, and manageconnections and activities. This chapter documents its features andbehaviors.

27

LEI Administrator DatabaseThe LEI Administrator database (decsadm.nsf) is derived from the suppliedtemplate file leiadm.ntf. It is installed as part of the LEI installationprocedure.

At the time of installation, the design of an existing decsadm.nsf is upgradedto the LEI database, preserving existing connection and activity documents.This prevents the user from using both DECS and LEI concurrently on thesame Domino Server. See the Lotus Enterprise Integrator for Domino (LEI)Installation Guide for more information on configuring LEI and aboutmigrating documents from an existing Release 3.n LEI Administrator to this release of LEI.

A single LEI Administrator can hold information used by several LEI servers,but each LEI server can be governed by only one LEI Administrator. A groupof LEI servers governed by one LEI Administrator is called an LEI cluster.

The LEI Administrator database interacts with a log database thatdocuments the processing and outcome of activities and server operations.This is described later in this chapter.

Note Do not use Notes replication on the LEI Administrator database. LEI server operations such as scheduling and status checking will beseriously disrupted.

Configuring Administrator SecurityThe LEI Administrator uses security features available with Lotus Notes,such as encryption and true Access Control List (ACL) author access. Sinceseveral types of users can use LEI, you should carefully plan your securityimplementation. Lotus recommends that one person, or group of people, bedesignated as the LEI Administrator manager. This person or group shouldbe responsible for installing LEI and editing configuration documents.Using the security features of Lotus Notes (such as ACL author-levelprivileges), these documents can be made inaccessible to other users.

Note The default access on the supplied LEI Administrator is Manager.Each LEI customer’s database manager or system administrator is urged torestrict this Manager access to the appropriate (typically small) group ofusers during installation or immediately after installing LEI to preventunauthorized user access to the database. Additional managers can beadded at or after LEI installation by adding entries to the access control list.See the Lotus Enterprise Integrator for Domino (LEI) Installation Guide forrelated information.


Encryption of database passwords is an important part of LEI’s securityfeatures. All password fields are encryption enabled. Encryption keys foreach form must be made and added to each LEI server’s ID as well as toanyone’s ID who may need to see or make changes to the encrypted fieldsor to the document itself. Those users who do not have the encryption keymay still view the document but will not see any data in the encrypted field.The encrypted field remains blank. Additionally, users without theencryption key will not be able to edit the document.

Configuring LEI password encryption is described in the Lotus Connectorsand Connectivity Guide (lccon6.nsf and lccon6.pdf supplied with Dominoand also available at http//www.notes.net). Also, encryption in AdvancedRealTime Activities, such as Virtual Fields, Virtual Documents, and VirtualAgents, are documented in this manual in its respective activity chapter.

The LEI Administrator provides author privileges at the document level.Each LEI document has an action button in the action toolbar that accessesthe author privileges list.

Another part of security is reader access. When the encryption button isused in a document, the first part of the dialog displays the reader accesslist. Disabling the option “Who can read this document: All readers andabove” and picking names from the list allows only those names to see thedocument. No one else will be able to view the document, including thedocument’s author, if their name has not been chosen as part of the list.

Please see the Administrator’s Guide for Lotus Notes and the DatabaseManager’s Guide for more detailed information on Lotus Notes securityfeatures.

LEI Administrator Action BarThe LEI Administrator contains the buttons you need to create connectionsand activities. It also contains buttons you can use to start and stopactivities and display the current activity log.

Note See the section entitled, “Obtaining Help and Opening UserDocumentation” in Chapter 1 of this guide to learn how to obtain userassistance as you are creating, editing, and deleting activity and connectiondocuments. You can select the Create button in the top bar as an alternativeto the Add Connection and Add Activity action buttons. You can also select

Chapter 3: LEI Administrator 29

the Actions button in the top bar as an alternative to the Stop Activity actionbutton.

The LEI Administrator action bar buttons are described below.

• 1. Add Connection — Creates a new Connection Document for anexternal data source.

When you click the button you are presented with a list of possibleconnection types. Make your selection and a new ConnectionDocument appears. You can optionally enable the User Assistant toopen the Connection Document with explanatory text at the top of thedocument. Creating connections is described in the companiondocument Lotus Connectors and Connectivity Guide. Popup help is alsoavailable on the document.

The available connection types are DB2, File, Notes, ODBC, OLE DB,Oracle, Sybase, Test, Other (Collapse/Expand Metaconnector, MeterMetaconnector, Order Metaconnector, and Trace Metaconnector).

The User Assistant toggle is located in the Help area of the Navigatorpanel.

• 2. Add Activity — Creates a new Activity Document.

When you click the button you are presented with a list of possibleactivity types. Make your selection and a new Activity Documentappears. If you wish to create one of the three Advanced RealTimeactivities (Virtual Agents, Virtual Documents, and Virtual Fields) youcan optionally enable the User Assistant to prompt you through thecreation process. Creating activities is described in this guide. Popuphelp is also available.

The available activity types are Archive, Command, Direct Transfer,Java, Polling, Replication, Scripted, Virtual Agents, Virtual Documents,Virtual Fields, Admin Backup, and Admin Purge Log.

• Start Activity — Starts the Activity that is currently selected in theActivities view below the action bar.

This has no effect if the selected activity is already running.

• Stop Activity — Ends execution of the currently selected Activity.

This has no effect if the current selection is not running.

• Current Activity Execution Log — Displays the status of the currentlyselected Activity.

If the selected Activity is running, the start time and current status aredisplayed. If the selected Activity is not running, the results of the mostrecent execution are displayed.


You can optionally view all Activity logs by clicking the Log option inthe Log History area of the Navigator panel.

LEI Administrator Navigator and View OptionsThe Navigator panel on the left side of the LEI Administrator enables youto view activities, connections, and configuration documents in the viewingarea of the LEI Administrator. It also allows you to group activities and/orconnections using user-defined folder names. The Help section of theNavigator enables you to toggle the User Assistant on and off and quicklyopen the online documentation. The Navigator also allows you to quicklydisplay log history by server and type.


The Navigator panel options are described below.

• Activities — Using this option, you can view activities in one of thefollowing four possible ways. The Activity Documents can be openedand edited from this view. An activity view also displays activity nameand status, such as “Completed successfully” or “Has not run”.

• By Type (default) — Select this option to display all activities,grouped by activity type, in the activities view.

• By Category — Select this option to display all activities andconnections that contain a shared Category name, grouped by thatCategory name, in the activities view.

Connection Documents, Configuration Documents, and ActivityDocuments contain an optional Category field that enables you toenter a name that can later be used to group documents by thatCategory name.


• By Advanced RealTime — Select this option to display the followinggrouped activity types in the activities view: Virtual Agents, VirtualDocuments, and Virtual Fields.

The information in the Advanced RealTime view displays the DominoApplication (and the form used), the events that the Activity performs(such as, open, update, and so on), Activity type, the external source,the status of the Activity, and the name of the Activity.

• By Data Management — Select this option to display the followinggrouped activity types in the activities view: Archive, Command,Direct Transfer, Java, Polling, Replication, Scripted, Admin Backup,and Admin Purge Log.


• Connections — Select this option to display all connections, grouped byconnection type. The Connection and Metaconnection Documents canbe opened and edited from this view. Both the Name and ExternalSource columns can be sorted by the user in order to easily locatedocuments.

• Configuration — Select this option to display the configurationdocuments for the LEI server and the LEI Administrator. You can openand edit these documents as required. There is one server documentand one administrator document. For more information about serverand administrator configuration documents, see “LEI ConfigurationDocuments” later in this chapter.


• Project Organizer — Select this option to see the Project Organizerview. Using this view, you can optionally create folders, and placeparticular connections and activities in those folder, for the purposes ofgrouping by project or some other user intent. For example, you maywish to group connections and activities together that pertain to aspecific task.

You can create folders here by clicking Create — Folder in the Dominotop bar menu. Use a name that reflects the kind of information you aremonitoring.

Once you have created a folder, drag and drop the desired connectionsand/or activities into that folder and then display the folder contents inthe view.

• Help — Using this option, you can toggle the User Assistant on and off,open the online documentation, and learn more about the LEIAdministrator database itself.

• Turn User Assistant On/Off — Click this option to enable or disablethe User Assistant. When the User Assistant is on, ConnectionDocuments open with explanatory text at the top. If you are creatinga Virtual Fields, Virtual Documents, or a Virtual Agents Activitydocument, the User Assistant guides you through the process ofcreating that Activity Document.


• LEI Documentation — Select one of the LEI online manuals from thelist to open the associated .nsf file. Navigate to the needed topicusing the panel of topic contents in each guide.

IBM Lotus Enterprise Integrator for Domino (LEI) Activities and UserGuide (leidoc.nsf)

Lotus Connectors and Connectivity Guide (lccon6.nsf)

Lotus Connector LotusScript Extensions Guide (lsxlc6.nsf)

IBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide(leiig.nsf)

These online manuals are also supplied in PDF format and can befound at http://www.notes.net.

• About this Database — Select this option to open a document thatdescribes how to use the Administrator.

• Log History — Select the Log option to view all of the log filedocuments by server or type. You can optionally open and view thesedocuments.

Active View OptionSimilar to the Log History option in the Navigator, the Active View option,which appears at the bottom of the LEI Administrator underneath theActivities or Connections view, enables you to display anything that iscurrently running. The window can be expanded or collapsed as needed byclicking the heading to display the active servers and the currently runningactivities. You can double-click the Activity or Active Servers headings toexpand or collapse the list. You can also double-click an entry to open theassociated document or log history. The window allows you to stop acurrently executing activity or view the activity execution log while theactivity is in progress.


Activity Status IndicatorsThe following table describes the status indicators shown in an Activitiesview. These icons may appear in different locations depending on theActivity. To refresh an Activities view, press the F9 key.

Indicates the Activity is a Virtual Documents Activity

Indicates the Activity is a Virtual Fields Activity

Indicates the Activity is a Virtual Agents Activity

Icon is displayed indicating whether the Activity is a Virtual Fieldor a Virtual Document Activity:

Activity

Indicates Virtual Attachments are enabled in this Activity

Indicates the Activity will process document deletions

Indicates the Activity will process document updates(edit/save)

Indicates the Activity will process document opens

Indicates the Activity will process document creations

Shows the type of event being monitored by this Activity. Used inthe Advanced RealTime activities view.

Events

Activity scheduled to start and stop at specified times

Activity not scheduled

Activity scheduled to AutoStart with server

Activity disabled with an error

Activity stopped with an error

Starting / Stopping an Activity

Active Activity

Shows the status of the Activity, as indicated by the icons below.Refresh the view periodically to update the status.

Status

Description and IconColumn


LEI Administrator Menu CommandsIn addition to the standard Notes commands found in the Domino top barmenu, the LEI Administrator provides additional commands.

CreateWhen you select Create from the Domino top bar menu, the followingLEI-specific options appear.

• Other — This option enables you to choose a Metaconnection type tocreate. You can also create a Metaconnection using the AddConnections button in the LEI Administrator.

• Agent — This option enables you to create an LC LSX agent.

• Folder — Used in conjunction with the Project Organizer option on theNavigator, this option enables you to create a custom-named folder forthe purpose of grouping specific connections and/or activities.

• View — This option enables you to define an activity or connection view.

ActionsWhen you select Actions from the Domino top bar menu, the followingLEI-specific options appear.

Activity AdministrationThe Activity Administration menu provides commands related to activities.

continued

This command immediately terminates an Activity process.

Note The preferred method of stopping an Activity is theStop (Activity) command, which provides an opportunity forthe Activity to clean up its database connections and log thetermination. Using the Kill command may leave the system inan unstable state due to improper termination of the Activity,so only use it when absolutely necessary. LEI considers killingan Activity an error.

Kill Activity

The ClearLock agent clears an Activity document’s Lock fieldso that the Activity can be run again.

The purpose of the agent is to provide a manual way to clearthe lock in case an LEI server goes down while running theActivity and you want to run the Activity before theautomated server cleanup occurs.

Select the documents from a view before running this agent.The agent ignores non-activity documents.

Clear Lock

DescriptionCommand


This command stops a selected Activity that is currentlyrunning. Stop (Activity) is the preferred method (rather thanthe Kill command) of prematurely terminating an Activity.

When an Activity is closed, LEI does not consider it an error.LEI will not mark the Activity as failed, and does not sendmail notification on error. The Activity is not completed andthe Activity and dependent activities are not executed.

Note To immediately close an Activity process, use the Killcommand.

Stop Activity

Use this agent when a server configuration document hasbeen unintentionally destroyed.

Since LEI identifies servers through an ID rather than byname, all activities using the server field will be synchronizedwith the new server ID. The agent acts on selected activities.

Set DesignatedServer

DescriptionCommand

LEI Server AdministrationThe LEI Server Administration menu provides commands related to theoperation of the LEI server. These commands are described below.

This command immediately terminates the LEI server.

It prevents the LEI server from starting any new activities andsends a Stop (Activity) command to all currently runningactivities. After the time period specified in the serverconfiguration document’s Activity Request ShutdownTimeout field (in the Administrator database), any activitiesthat are still running are Killed (see the Kill command) andthe LEI server program stops.

Note The preferred method of terminating the LEI server isthe Shutdown Server command.

Stop Server

This command terminates the LEI server.

Shutdown Server is the preferred method (over the StopServer command) of prematurely terminating a server. Itprevents the LEI server from starting any new activities andwaits for all currently running activities to shut down. Whenall activities have shut down, it stops the LEI server program.

To immediately terminate the LEI server, use the Stop Servercommand.

Shutdown Server

DescriptionCommand


Reset ActivityThis command restarts the currently selected Activity.

Set AutostartWhen this option is turned on all the selected activities start when Dominostarts. Clicking “Off” turns off this option for the selected activities.

Remove from FolderRemove the selected Activity and Connection Documents from thecurrently opened folder. This option is only available when you are in aProject Organizer folder.

Creating, Editing, and Deleting DocumentsYou can create Connection Documents, Activity Documents, andMetaconnection Documents using the LEI Administrator.

Note Administrator and server configuration documents are created whenLEI servers are installed. See “LEI Configuration Documents” in thischapter for more information about administrator, server, and clientconfiguration documents.

Note See the section entitled, “Obtaining Help and Opening UserDocumentation” in Chapter 1 of this guide to learn how to obtain userassistance as you are creating, editing, and deleting activity and connectiondocuments.

Creating New LEI DocumentsThis section provides a very brief overview of the process for creatingConnection and Activity Documents in LEI. This process is documented ingreat detail, per each activity type and connection type, in the companiondocument Lotus Connectors and Connectivity Guide and this guide.

To create an LEI Connection Document or Activity Document, do thefollowing:

1. Start Lotus Notes.

2. Open the LEI Administrator (decsadm.nsf).


3. Click the Add Connection or Add Activity icon from the action bar.Alternatively, you can select the Create button from the Domino topbar.

Note You cannot create an activity until the needed connectiondocuments have been created.

4. Choose the kind of document that you want to create (for example, DB2Connection or Direct Transfer Activity.

5. Enter information into the document as needed.

Note You can select from a list where multiple choices are possible.Click the down arrow icon to display the fields available in theavailable external data. This is referred to as “browsing”. The externalmetadata is queried each time that you click the down arrow icon,therefore no refreshing of the cache is required as in previous releasesof LEI. In most cases, you may also type entries in manually, however,using both manually typed entries and browsed entries may result inunpredictable results or error messages and is not currently supported.If you choose to create the activity using the “browsing” feature, usethis feature throughout the document. If manual entry is preferred,manually type throughout the document. See the section entitled,“Understanding Basic Browsing” later in this chapter for properconfiguration of connectivity to external data sources.

When completing the fields, follow these guidelines:

• Some entries are made by selecting from a list. The labels of theselists are followed by the standard Notes entry helper button. Clickthe arrow to the right of the field to see the key list and click theselection that you want to make.

• Small blank buttons on the form provide access to additional optionswhen clicked.

• Red field brackets indicate encryption-enabled fields.

• All documents contain an optional Category and Comments fieldsthat can help you manage your documents.

Category — Enter a category name. This option enables you to groupa set of documents by like category name. If the category name youenter doesn’t exist, it will be created when you save the document.You can enter multiple category names, separated by commas.

Comments — Enter text to describe the document. This is a rich textfield, you can place anything here, including links to otherdocuments.


6. You can use Notes Reader and Author list privileges to add additionalsecurity to Activity and Connection Documents. To add or updateauthors of the document, click the Author Privileges action button for alist of three options for managing Author access. Select an option andclick OK to use it. Document authors are people who will haveauthorization to edit the document once it has been created. Privilegesand ACL information for LEI usage is thoroughly documented in theIBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide.

• Add name[s] to document editor list.

Select this option to add a name(s) from the Domino Directory(formerly referred to as the Public Name and Address Book) to thelist of editors for this document.

• Remove a name from document editor list.

Choose this option to delete a name from the list of documenteditors.

• View document editor list.

Choose this option to view the list of current editors for thedocument.

7. Save the completed form by clicking the Save & Exit button at the top ofthe form. Alternatively, you can choose File - Save from the top barmenu.

Editing Existing DocumentsTo edit an existing Activity Document or Connection Document, do thefollowing:

1. Open the LEI Administrator (decsadm.nsf).

2. Choose a view from the LEI Navigator.

3. When the document appears, double-click the name of the document inthe view.

4. Enter the Edit mode using one of the following methods:

• Press the Ctrl + E keys.

• Choose Edit Document from the Action menu.

• Choose the Edit Document button at the top of the form.

• Double-click anywhere in the document.

5. Make the desired changes to the document.

6. Save the document by clicking the Save & Exit button at the top of theform. Alternatively, you can choose File - Save from the top bar menu.


Deleting DocumentsWhen you no longer need a document, you can delete it, provided that youhave appropriate access rights.

Note When deleting Connection Documents, you must know whether ornot they are used by other documents. You can sort Activity view byConnection by clicking the Source or Target Connection column heading inthe Activity view. Deleting a document whose name remains in anotherdocument will cause an error when that Activity is run or when you try toopen a dependent document.

Note Do not delete configuration documents; they should be deleted onlyby the LEI install or uninstall utility.

To delete an Activity Document or Connection Document, do the following:

1. Open the LEI Administrator database (decsadm.nsf).

2. Choose a view from the LEI Navigator, for example Connections.

3. Select the document you want to delete and press the Delete key. Thedocument will be deleted when you close or refresh the view.Alternatively, on a Win32 platform you can select the document andpress the Ctrl + X keys to immediately delete the document and itsdisplay from the view.

Activity Document Action BarLEI Activity, Connection, Metaconnection, and Configuration Documentsmay include the following action buttons when they are opened for viewingor editing. Other buttons, specific to a given activity or connection type,may also be present. Such buttons are documented with the applicableactivity or connection type.

• Author Privileges

• Edit Document

• Start!

• Save & Exit


Author PrivilegesThe Author Privileges option allows you to change author privileges for thedocument currently being edited. You can add additional security toActivity, Metaconnection, Connection, and Configuration Documents.Document editors are people who will have authorization to edit thedocument once it has been created.

To change Author Privileges for the Activity, perform the following tasks:

1. Click the Author Privileges action button. The Author Privileges dialogbox appears.

2. Choose the action you want from the options available in this dialogbox. These actions include:

a. Add name[s] to document editor list.

Choose this option to add a name(s) from the Notes Public Nameand Address Book (Domino Directory) to the list of editors for thisdocument.

b. Remove a name from document editor list.

Choose this option to delete a name from the list of documenteditors.

c. View document editor list.

Choose this option to view the list of current editors for thedocument.

Edit DocumentSelecting this action button opens the current document for edit. It alsotoggles the Save and Exit action on.

Start!Selecting this action button causes the Activity to be run the next time theLEI server polls the LEI Administrator database. In previous releases, thisbutton was named Run ASAP.

Click the Start! button when you want to run an Activity as soon aspossible. LEI runs the Activity the next time the LEI server polls the LEIAdministrator. The Start! button is available only from an ActivityDocument after the document has been saved.


Save and ExitSelecting this action button saves the changes that you have made to adocument.

Understanding Basic BrowsingEarlier releases of LEI used client-side browsing from the LEIAdministrator, which required that LEI users install their external systemconnectivity software on both the Domino server (that hosted the LEIAdministrator and the LEI server) and the Notes client. This is no longertrue. LEI now uses server-side browsing. Browsing databases on theexternal system uses client connectivity from the Domino server that hoststhe LEI Administrator.

External system connectivity software should be installed on the Dominoserver that hosts the LEI Administrator and that also hosts the LEI server. Ifyour Domino server and LEI server are on different machines, you mustinstall your external system connectivity software on both machines. LEIusers no longer need to install external system connectivity software on theNotes client.

Browsing and the Domino DirectoryCertain security settings are required in the Domino Directory where theLEI Administrator resides. In the Security tab of the Domono server’sServer Configuration Document, the “Only allow server access to userslisted in the directory” option is set to “Yes” by default. However, tobrowse the server, set the “Only allow server access to users listed in thedirectory” option to “No.” Ensure that all users who will be creating LEIActivities have entries in the Domino Directory and that the server is listedas part of a group. For more information, see the pop-up help in the ServerName and Address document.

Other Domino Directory setting requirements are described in the LotusEnterprise Integrator for Domino (LEI) Installation Guide in the introductorychapter and in the “Preparing to Install LEI on Windows” and “Preparingto Install LEI on UNIX” sections of its Windows and UNIX chapters,respectively.


Buffering ListsWhen the list of tables is lengthy, you can scroll down the list to find the tableyou want to select. However, if the table list is too long to be completelyaccommodated by scrolling, an overflow message appears at the bottom of thelist (<overflow…>). A box also appears under the list, which you can use toenter the exact name of the table you want to use. See the illustration below.

Note The number of tables that the scrolling window can accommodate is dependent on the number of characters in the table names. If table namesare short, more tables will be viewable by scrolling than if table names are long.


Configuring BrowsingTo enable browsing of Notes databases on a remote Domino server, youmust edit the names.nsf file (Domino Directory — formerly referred to asthe Name and Address Book or NAB) that resides on the remote Dominoserver. This procedure is thoroughly documented in the Lotus EnterpriseIntegrator for Domino (LEI) Installation Guide in Chapter 2, “Installing andConfiguring LEI on Windows” and Chapter 3, “Installing and ConfiguringLEI on UNIX” in the following section titles:

• Setting Access Controls in the Domino Directory

• Establishing Access Rights in Your Notes ID File

LEI Configuration DocumentsThere are two LEI configuration documents available; Administrator andServer.

These documents define parameters for the LEI Administrator databases,LEI client databases, and LEI servers, respectively. These documents areaccessible using the Overview option in the LEI Navigator or using theView menu under System Overview.

Administrator ConfigurationEach LEI Administrator database contains a single Administratorconfiguration document. The Administrator configuration documentcontains configuration information about the Administrator and the LEI servers.


The Administration Configuration document identifies the followinginformation.

Specifies the interval, in minutes, at which each running LEIserver must notify the Administrator database of its status.Any LEI server that fails to update its status in three of thesetime periods is assumed to have terminated abnormally.

The interval value must be entered in minutes and defaults toa value of 60.

The status of the server is reported in the serverconfiguration document along with the date and time of thelast broadcast received.

Status BroadcastInterval

Specifies the file path and name of the optional repository forScripted Agents, relative to the standard data directory.

Scripted AgentDatabase

Specifies the file path and name of the LEI help databases onthe Domino server, relative to the standard data directory.

Help Database

Specifies the file path and name of the LEI log database onthe Domino server, relative to the standard data directory.

Log Database

DescriptionField Name

Server ConfigurationThe LEI Administrator contains a server configuration document for eachLEI server that it controls. The document contains configurationinformation relevant to the LEI server. An example is shown below.

The server configuration document identifies the following information.

Note Changes made to the LEI server’s configuration document (such asPoll Interval, Maximun Duration of Activities, and Activity ShutdownRequest Timeout) do not take effect until you restart the LEI server.


continued

Specifies the amount of time in seconds that anActivity has to respond to a Close commandbefore it is terminated. Zero stands for notimeout.

Activity Shutdown RequestTimeout

Specifies the greatest number of consecutivefailures that a single Activity can have beforethe server no longer schedules it for execution.Zero stands for no disabling.

Maximum Consecutive Failures

Specifies the longest duration, in minutes, thatthe server will run any single Activity. Theserver automatically closes any Activity thatexceeds this duration. Zero stands for notimeout.

Maximum Duration of Activities

Specifies the greatest number of concurrentActivities that the server will run. Once theserver is running the maximum number ofActivities, it postpones additional Activitiesuntil existing Activities are concluded. Zerostands for no maximum.

Maximum Number of Activities

Specifies the interval at which the LEI serverpolls the Administrator database to see if thereare any Activities that it needs to execute.

Poll Interval

Specifies the name of the LEI server given atinstall time. This information cannot bemodified. See the IBM Lotus EnterpriseIntegrator for Domino (LEI) Installation Guide formore information.

Server Name

Click the view log icon (if available) to see thelatest log document for this server.

View log (button)

Specifies the date and time that theAdministrator last received a status updatefrom the server. Like the Current Status, thisinformation cannot be modified. The frequencyof broadcasts is the one entered in theAdministrator configuration document.

Last Broadcast

Specifies the status of the server. Thisinformation cannot be modified directly. Thestatus is Active or Inactive.

Current Status

DescriptionField or Button


Name of server that hosts Domino. It may bethe same as or different from the server thatLEI has been installed on.

Advanced RealTime Enabled: Mark this box tonotify LEI that the specified Domino server canrun Advanced RealTime Activities.

Note See the IBM Lotus Enterprise Integrator forDomino (LEI) Installation Guide for moreinformation about how to setup a Dominoserver so that it is enabled for AdvancedRealTime Activities.

Domino Server

DescriptionField or Button

LEI LogLEI maintains a log for all LEI servers and activities. The LEI log is usefulfor tracking performance and for troubleshooting. To view your LEI log,select Log from the Navigator, then double-click the specific entry you wantto look at.

Server LogThe following information appears in the server log document:

Includes the history of processing undertaken by the LEI server,including specific activities with their start and stop times,server status, and any error messages that may have occurred.

Individual lineitems

Specifies the date and time that the LEI server was started andterminated, marking the duration of the server’s Activity duringthis log entry. The date/time format depends on the currentNotes client operating system.

(Date/timeinterval)

Specifies the name of the LEI server.Server

DescriptionField


Activity LogShown below is an example of an LEI Activity log. Activity logs provideinformation about LEI activities that enable you to track systemperformance and results. The information in an Activity log includes thename of the Activity, the server that processed it, the start and finish dateand time, and a summary of statistics.

The following information appears in the Activity log document:

Specifies the number of records that were deleted fromthe external system.

Records Removed

Specifies the number of records that were updated intothe external system.

Records Updated

Specifies the number of records that were inserted intothe external system.

Records Inserted

Specifies the number of records that were fetched fromthe external system.

Records Fetched

Specifies the duration of the Activity in the formathh:mm:ss.

Elapsed Time

Includes the history of the Activity’s processing,including event and error messages.

Individual line items

Specifies the Activity’s start and end date and time. Thedate/time format depends on the current Notes clientoperating system.

(Date/time interval)

Specifies the name of the LEI that ran the Activity.Processed by Server

Specifies the name of the Activity.Activity

DescriptionField


Operation LogThe operation log holds any LEI system reports. LEI will only create one ofthese reports when an error has been detected within the LEI Administrator.As an example, if the scheduling information for an Activity were corrupted,then an operation log would be created to point out the Activity and theaffected data.

An example of an operation log is shown below.

The following information appears in the operation log document:

Lists any operational problems.(Individual line items)

Specifies the date and time that the events logged tookplace.

(Date/time interval)

Specifies the name of the server for which the log wasgenerated.

Generated for Server

DescriptionField


LEI Script VaultThe LEI Script Vault (leivlt6.nsf) is supplied with LEI. You can choose tocreate it when you install LEI. It can be used to store the LC LSX scripts(agents) that you create for use with LEI.

The option “Catalog All Agents”, available at the View level, inventoriesthe agents and creates a tracking document for each. This trackingdocument contains information about each agent, such as its name andcreator, and allows you to add additional comments. When you open theLEI Script Vault, select “Catalog All Agents” to update the agent trackingdocument so that agents appear in the view just like documents would.Each time you select the “Catalog All Agents” option, the agent trackingdocument is updated, new agents are cataloged, and tracking documentsthat no longer have associated agents are deleted.

The LEI Script Vault is supplied with two agents for use with the thesupplied sample database leipackagetrack.nsf. The Tutorials appendix ofthis guide describes how to create a Scripted Activity using these suppliedagents with the sample database leipackagetrack.nsf.

The LEI Script Vault should be included in regular backup procedures.

Note Only the agents in the LEI Script Vault (leivlt6.nsf) that have beencreated as shared agents are copied during the Admin Backup Activity. TheAdmin Backup Activity does not copy private agents from leivlt6.nsf to thetarget database. To ensure that your agents are copied to the target backupdatabase during the Admin Backup Activity, enable the Shared Agentoption in Domino Designer when you create your agents.


Chapter 4 Introduction to Connectors

Several Lotus Connectors are supplied with LEI.

Lotus Connectors Supplied with LEIThe following Lotus Connectors are supplied with LEI:

• Notes

• DB2

• ODBC

• Text

• File

• Sybase

• Oracle 7

• Oracle 8

These Connectors are described in the companion document Lotus Connec-tors and Connectivity Guide. The documentation file names are lccon6.nsf andlccon6.pdf. The lccon6.nsf file is supplied with Domino, not LEI, but isreachable using the Help button on the LEI Administrator. The lccon6.pdffile is located at http://www.notes.net. Related information can be found inthe Lotus Connectors LotusScript Extensions Guide. The documentation filenames are lsxlc6.nsf and lsxlc6.pdf. The lsxlc6.nsf file is supplied withDomino, not LEI, but is reachable using the Help button on the LEI Admin-istrator. The lsxlc6.pdf file is located at http://www.notes.net.

For iSeries users, contact your system administrator to determine whichLotus Connectors are available.

For more information about these and additional premium Lotus Connec-tors, visit the following Web site:


55

Chapter 5 Introduction to LEI Activities

This chapter provides an introduction to LEI Activity Documents. Itincludes an introduction to Activity Documents, descriptions of fieldscommon to all Activities, Activity scheduling options, definition ofAdvanced RealTime Activities, and information about command lineexecution of Activities.

Introduction to Activity DocumentsActivity Documents contain the information that instructs the LEI server toexecute an event, such as a data transfer. Each Activity type has a specificNotes form that can be used to create the Activity. Each LEI Activity isdescribed briefly below. For more information, refer to the specific chapterfor each Activity.

Note Advanced RealTime consists of three Activities - Virtual Fields,Virtual Documents, and Virtual Agents.

continued

This activity creates Domino agents that run storedprocedures on the external system database.

Virtual AgentsAdvanced RealTime

This activity provides functionality that is similar to VirtualFields, however, it does not require key documents andmake it possible to have a Notes database with a very smallfootprint access a very large amount of data from anexternal source.

Virtual DocumentsAdvanced RealTime

This activity provides real-time access from a Dominoapplication to a supported external data source, such asDB2.

Virtual FieldsAdvanced RealTime

This activity polls a database to see if a specified conditionexists, and, if so, executes an activity.

Polling

This activity executes a user-specified Java application.Java

This activity transfers data from one database to another.Direct Transfer

This activity executes an action against a database.Command

This activity archives a database.Archive

DescriptionActivity

57

This activity purges the LEI logs.Admin Purge Log

This activity backs up the LEI Administrator database data.Admin Backup

This activity executes an activity whose data sources andfunction are defined by a LotusScript script.

Scripted

This activity synchronizes data in different databases. Replication

DescriptionActivity

Creating ActivitiesThe process for creating LEI Activities is described in the LEI Administratorchapter in the section entitled “Creating, Editing, and DeletingDocuments”. It is also described at the beginning of each Activity chapter inthis guide.

While building an Activity, you can choose connection information fromexisting Connection Documents. You should create any ConnectionDocument that you intend to use before you create the activity. See thecompanion document Lotus Connectors and Connectivity Guide for informa-tion about how to create or edit a Connection Document. This document issupplied with Domino, not LEI, but is reachable using the Help button onthe LEI Administrator. The PDF equivalent is located athttp://www.notes.net.

All connections referenced in the Activity should exist and be valid. To test the validity of a connection, use CONTEST as described in the LotusConnectors and Connectivity Guide.

Activity Documents use Notes collapsible sections to contain activity optionsets. Most Activity Document fields are browseable, enabling easy pointand click access. Browseable fields are not editable.

Browsing Connections from within an ActivityLEI supports server-side browsing. Browsing connections on an LEI serverthat resides on a Notes client, and not on the Domino server hosting the LEIAdministrator, is not supported. If your LEI server is on a local client, andyou want to connect to a local LEI database, you must type in the metadataand field names on the Activity Document.

When browsing, the Domino server hosting the LEI Administrator searchesfor the database named in the Connection Document. If that database resideson a Notes client (not the Domino server hosting the LEI Administrator), LEI browsing cannot connect to the server to perform cataloging against it.


When using a Notes connection to a local database, browsing metadata andfields from the LEI activity yields the following error message:

Cannot use a Notes connection to a local database - error: No such databaseexists

Common Activity Fields and ButtonsThe fields and buttons described below are common to most Activitydocuments.

Author Privileges Action ButtonThis button appears in the Action Button Toolbar for all Activities. It allowsthe author of the document to view and change author privileges.

Activity Name and StatusThe name and status fields that are common to all Activity Documents aredescribed below.

continued

Indicates the status of the document as reported by the server. Thestatus can be any of the following:

New — The Activity has not yet been saved. This status appearswhile the Activity is being built.

Not Yet Scheduled — The Activity’s schedule has not been enabledsince its creation.

Scheduled for… — The Activity is enabled and scheduled to beexecuted at the time indicated.

Active on… — The Activity is currently running on the listedserver.

Scheduling Disabled but Running — The Activity has been queuedto run but has not started running yet.

Disabled but Running — The Activity is disabled but is currentlyrunning as a result of being executed.

Disabled — The Activity’s schedule is currently disabled. Toenable the schedule, open the Activity document in Edit mode andchange the Enabled/Disabled field to Schedule Enabled.

Current Status

Specifies a user-defined name and serves as a unique identifier forthe Activity. This uniqueness is enforced through a validationprocess when the Activity is saved. The character maximum is 127.

Name

Displays the user name of the person who created the Activity.Author

DescriptionField

Chapter 5: Introduction to LEI Activities 59

Displays the log document. Click the Log document icon (ifavailable) to see the log document for the last execution of thisActivity.

Log Link

Indicates what happened in the last run. If the Activity has neverrun, you’ll see the caption “Activity has not yet run tocompletion.”

Result

Shows the date and time that the Activity last ran (successfully orunsuccessfully). A zero means that the Activity has never beenexecuted.

Time

Shows the time and result of the last run.Last ComputedRun

DescriptionField

General OptionsThe General Options fields let you define general Activity information.These options are described below.

continued

Lists another Activity or Activities that will run when the currentActivity executes successfully.

With dependent Activity(s) you can connect the execution of twoor more Activities. Activities must be defined (in their ownActivity Documents) before they can be added as a dependentactivity.

DependentActivity(s)

Optionally specifies the LEI server.

If no LEI server is specified here, the first server to poll thecontrol store, when the Activity is scheduled to run, will executethe activity.

If a server is specified here, only that server can run the Activity.

DesignatedServer

DescriptionField


Enter the Notes user names of the people who should receive theEmail notification. Use a comma to separate the names.

Email Recipients

Specifies whether mail should be sent Never, Always, or OnError. With the On Error option, mail is sent only when theActivity does not complete successfully.

Send Log as Plain Text — By default, the log report and statusare sent to the recipient in Notes rich text format with a doclink.Enabling this option sends the mail in plain text format instead.This option is provided for use when sending Email to a pager orPDA device.

Send Log andReport Status

Enable Logging — If Enable logging is selected, an Activity logdocument is created for each execution of this Activity. Whenyou select this option, the other logging options become availablein the user interface.

Buffer Logging — If Buffer Logging is selected, log entries arestored in memory until the conclusion of the Activity. When theActivity is complete, log entries are written to the log database. IfBuffer Logging is not selected, log entries are written to the logdatabase as they are generated.

Logging

Sets a time-limit in minutes for how long an Activity can runbefore being terminated.

A setting defined here overrides the maximum duration time setin the server configuration for the server that executes theActivity. Zero stands for no timeout.

MaximumDuration of ThisActivity

Assigns a low, medium, or high priority to the Activity.

In a multitasking environment, the LEI server allocates resourcesbased on priorities. A high priority gains more LEI resourcesthan a medium or low priority.

OS Priority

DescriptionField

SchedulingSee the “Activity Scheduling Options” section later in this chapter.


Category and CommentsThe Category and Comments fields enable you to optionally categorizedocuments and add comments.

Enables you to add descriptive content. Use this field todescribe the document. This is a rich text field, so that you canplace anything here, including document links.

Comments

Enables you to specify a category name. Entering a categoryname allows you to group a set of documents by category in theActivities by Category view. If the category you enter doesn’texist, it will automatically be created. You can only enter asingle category per document.

Category

DescriptionField

Activity Scheduling OptionsThe Scheduling section defines the schedule according to which the Activityis to be executed.

Overview of SchedulingThe scheduling section of Activity documents is common for all Activities.The parameters affect the scheduling in a specific order. Additionally, theStart Activity icon in the Navigator or the Run ASAP action button eachmark the Activity to run as soon as possible regardless of the schedule.Neither of these affects the scheduled run time. It is important to note thatthe scheduling parameters affect when an Activity is scheduled to start.Additionally, for the Polling and Advanced RealTime Activities, the sched-uling information is used to determine when it should stop. More informa-tion about how the scheduling settings affect the stop time may be found atthe end of this section.


The first parameter of scheduling is the DISABLED/ENABLED/RESTRICTsetting. When an Activity is disabled, all of the other scheduling settings areignored. When enabled, the Activity will be scheduled to run according tothe setting of the remaining parameters. The Activity may actually runsome time after its schedule time if the LEI server is not available eitherbecause it is shut down or it is busy. In this case, the Activity will run assoon as possible after the server becomes available. If the Activity shouldnot run except at the schedule times, the RESTRICT TO SCHEDULE shouldbe used.

The next parameters to affect the scheduled run time are the Start Date andTime and Stop Date and Time. These create boundaries for the run time.Scheduling will not begin before the start date and will not continue afterthe stop date. As an example, a start date of June 6, 1999 and a stop date ofDecember 25, 1999 would prevent the Activity from being scheduled anytime before 00:00:00 AM on the 6th of June and would prevent it from beingscheduled any time after 12:59:59 PM on the 25th of December, 1999. If onlya time value is indicated for these parameters, then the current date isassumed.

Once the boundaries of scheduling are established, the Days of the Week,Weeks of the Month, and Days of the Month settings are used together todetermine which dates in the month are acceptable. First, any dates whichdo not fall on the selected Days of the Week, Days of the Month, or Weeksof the Month are ignored. For the purposes of scheduling, a week is a sevenday period starting with the first of the month. As an example, if the first ofthe month is a Thursday, then each week is Thursday through Wednesday.Both the Weeks of the Month and Days of the Month choices will acceptnegative numbers to indicate counting from the end of the month. Thisfeature is helpful for scheduling Activities to run on the last day of themonth or even the last Friday of the month. For example, to schedule on thelast day of every month, set Days of the Month to -1; to schedule on the lastFriday of the month, set Weeks of the Month to -1, Days of the Week toFriday.

The final parameters for scheduling are Repeat Interval and Run at Times.When specified, any times which fall outside the Run at Times settings areignored. The values may be any combination of distinct times such as 8:00AM, 11:30 PM and time ranges such as 7:00 AM - 3:00 PM. Once the initialrun time has been computed, subsequent run times are scheduled at therepeat interval. To maintain accuracy of the scheduling interval, the nextrun time of an Activity is computed at the start of the current execution.


This prevents variation in the amount of time it takes an Activity tocomplete from affecting its next scheduled run time. If an Activity does notcomplete until after the next scheduled run time, it will complete thecurrent execution and then restart immediately to complete the overduescheduled run.

For example, an Activity has a repeat interval of 60 minutes and typicallytakes only few minutes to complete. The Activity will run on its hourlyinterval such as 6:30 PM, 7:30 PM, and so on. However, if the second executiontakes more than 60 minutes to complete, the Activity will complete the 7:30PM run after 8:30 PM. It will then start the 8:30 PM run as soon as the previousrun is complete and, assuming it returned to its typical execution of only a fewminutes, would be scheduled for 9:30 PM. When an Activity repeatedlyoverruns its next start time, the scheduling is adjusted to prevent continuallyscheduling overdue times.

All of the scheduling settings are used to determine when the Activity willstart. For many Activities, they start according to the schedule and then runto completion. The Polling and Advanced RealTime Activities also use thescheduling settings to determine when to stop. The Run at Times, Days ofthe Week, Weeks of the Month, and Days of the Month settings are used todetermine valid start times. These same values are used to determineinvalid times. For Activities which require a stop time, the first invalid timefollowing the start time is computed and used as the stop time.

Note If no values are specified for Run at Times, Days of the Month, andWeeks of the Month, and every weekday is listed in Days of the Week, thenthere are no invalid times and the Activity will not have a stop time. Also,the start time is computed before the stop time. As described previously,the start time is computed using the Repeat Interval. It is possible to havethe next start time occur before the current stop time. For example, a NotesVirtual Fields Activity with valid run times being 7:00 AM - 3:00 PM and arepeat interval of 60 minutes would schedule to start at 7:00 AM and stop at3:00 PM. However, it would have its next run time computed as 8:00 AM.When the Activity completed at 3:00 PM, it would view the 8:00 AM starttime as overdue, and restart immediately. You can use the Restrict toSchedule setting to prevent this behavior. An alternative is to set the repeatinterval to 1 day, which causes the run time to be 7:00 AM each day. UsingRestrict to Schedule and setting the repeat interval to a small value has thebenefit of restarting the Activity immediately in the event it stopped priorto the computed stop time.


SchedulingThe scheduling process allows you to set two kinds of controls:

• The window of time during which the Activity can take place — Thiswindow can amount to an absolute start and stop date and time or to aregularly defined period (such as every weekday between 7:00 AM and6:00 PM).

• The Activity interval — The interval defines how often the Activity willbe executed within the schedule window, which can be from everyminute to every few months.

An Activity executes as soon as the window opens and on schedulethereafter. For example, an Activity scheduled to execute once an hourbetween 7:30 AM and 5:00 PM will first execute at 7:30, then at 8:30, andevery hour until its final execution at 4:30 PM.

To avoid scheduling inconsistencies between servers, the LEI administratorsupplies a standard time to the LEI server when it is started. As a result, allLEI servers supported by a single administrator operate on the same time.LEI considers Daylight Savings Time when necessary.

Note If you want the Activity to take place when an event occurs ratherthan on schedule, make it the dependent Activity of a Polling Activity. Seethe chapter entitled “Polling Activity” for more information.

The following fields in the Scheduling section of an Activity documentenable you to define when and how often an Activity is executed:

Basic Scheduling

continued

Causes the Activity to run only once on schedule when checked.If scheduled, the Activity will run on schedule but then will notrun again. After it is executed its Enabled/Disabled condition ischanged to Schedule Disabled. Using Run ASAP to execute anActivity does not count towards its Run Once status. Run Once isuseful for testing new Activities.

Run ActivityOnce andDisable

DescriptionField


continued

Specifies the window of time during which the Activity executes.The delimiting times can be entered in AM/PM or 24-hourformat and separated by a hyphen: 5:00 AM - 6:00 PM or 5:00 -18:00 or separated by commas (the combination 4:00, 8:00 - 10:00is valid). In either case, you must use the format hours:minutes (5PM and 1700 are not valid).

If no times are entered, the Activity can occur at any time.

Run at Times

Specifies the frequency of execution. The interval can be anynumber of minutes, days, weeks, or months. (Hours are enteredas multiples of minutes.)

Once an Activity is executed, its next run time is calculated byadding the interval to the last starting run time, as long as it fallswithin the window of execution defined in the Days of Week andRun at Times fields.

If an interval of once a day or greater is used and no time of daywindow is defined, the next execution will be scheduled formidnight at the start of the next valid day.

Repeat Interval

Specifies one of the three LEI scheduling options: ScheduleDisabled, Schedule Enabled and Restrict to Schedule. With thecursor in the edit field, press the space bar to toggle between thethree values.

Schedule Disabled — Will not run based on any of the remainingscheduling information, but can still be run by clicking the RunASAP button. Even though the Activity is currently “runningASAP,” the schedule status will still be shown as disabled.Shared execution also remains available.

Schedule Enabled — Will run based on the remaining schedulinginformation.

Restrict to Schedule — Similar to Schedule Enabled, but if theActivity execution starts outside a valid execution cycle, theActivity will not run and will be rescheduled for the next validexecution time. This option is used when an Activity should notexecute with a delayed start, such as when the scheduled runtime for an Activity passed while the LEI Server was down.When the server is started, overdue Enabled Activities start, butActivities marked Restrict to Schedule do not run until the nextscheduled time.

Activities are automatically disabled after a scheduled run if theRun Once option is checked.

Schedule

DescriptionField


Enables you to specify a retry interval should the Activity failprior to or during execution.

Activity Retry on Error — When enabled, allows you to specifyhow many times to retry running the Activity at intervalsspecified in minutes. This option is useful in cases where thedesignated server may not be available to service the first requestto run the Activity, so you would use this option to automaticallykeep retrying.

Note When you use the Activity Retry On Error option, anyretries that fall outside the specified schedule will not run. Thebase schedule will always dictate Activity run times, includingthe error retry attempts.

Retry Options

Specifies the weeks in the month to run the Activity. Use incombination with Days of the Month to finely control activityexecution scheduling.

Weeks of theMonth

Ensures that the Activity will execute every month on thespecified day(s).

Days of theMonth

Optionally ensures that the Activity will not be scheduled to runafter a specified date and time.

Stop Date andTime

Optionally ensures that the Activity will not run before aspecified date and time.

Start Date andTime

Specifies the days of the week on which the Activity will beexecuted. The Activity will be run during the Times of Day onlyon the days listed.

To choose days, place the cursor in the day field and press Enter.Choose from the list. You can also add or delete directly: pressthe first letter of the day to insert it, making sure that days areseparated by commas.

Days of theWeek

DescriptionField

Advanced SchedulingThe Advanced Scheduling options enable you to schedule an Activity toexecute on certain days or weeks of the month. It also allows you to specifya time in conjunction with a date.

When both Days of the Month and Weeks of the Month are defined, bothsets are valid. In other words, if weeks 1 and 2 and days 26, 27, and 28 aredefined, then the Activity will be available for execution on days 1 through14 plus 26, 27, and 28. The Activities, however, will always be limited to theDays of Week listed in the basic scheduling section. If the only listed day ofthe week is Monday, then the Activity will take place only when the daysdefined in the Advanced Scheduling section fall on a Monday.


This option specifies on which weeks of the month the Activity canbe executed. The weeks should be listed separated by commas.Weeks entered as negative numbers count back with -1 being thelast week (the last seven days of the month). If no weeks are listed,all weeks are valid (within the scope of other time-span definitions).

Weeks are seven day intervals starting with the first day of themonth, which may not necessarily be a Sunday to Saturday interval,and are defined as follows:

wwww Week 1 — Days 1, 2, 3, 4, 5, 6, 7wwww Week 2 — Days 8, 9, 10, 11, 12, 13, 14wwww Week 3 — Days 15, 16, 17, 18, 19, 20, 21wwww Week 4 — Days 22, 23, 24, 25, 26, 27, 28wwww Week 5 — Days (29), (30), (31)

Weeks of theMonth

This option specifies on which days of the month the Activity can beexecuted. Day 1 is the first day of the month. The days should belisted separated by commas. Days entered as negative numberscount back from the last day of the month with -1 being the last day.If no days are listed, all days are valid (within the scope of othertime-span definitions).

For example: 7, 15, 21, -1 means that the Activity can be executed onlyon the seventh, fifteenth, twenty-first, and last day of the month.

Range formats, such as 10 - 20, cannot be used. Each day in a rangemust be listed.

Days of the Month

The dates and times that define the span of time during which theActivity may be scheduled to execute.

You can set one or the other or both. A date and no time defaults tomidnight. When just a time with no date is entered, the current dateis used. If you intend to enter a start or stop date/time, however, it’srecommended that you enter both since the Administrator will notsupply the missing information into the entry field.

Enter a start or stop date/time only if you want to set a limit on thespan of time that the Activity should be scheduled to start running.You can leave a date/time blank to set no start or stop limit on theActivity schedule. If you leave the start field blank, the Activity isfirst run when the document is completed and saved.

An Activity that is running at Stop Time will continue to run until itcompletes, except for a Polling Activity, which, once started, runs upto Stop Time. If there is no stop time for the Polling Activity, it can stillbe stopped by using the Close command on the LEI server console.

The date and time format to be used is specific to the internationalsettings and the operating system on which the Notes Client isrunning.

Start/StopDate andTime

DescriptionField


Advanced RealTime ActivitiesAdvanced RealTime enables you to create the following three types ofRealTime Activities.

• Virtual Fields Activities (previously known as LEI RealTime or DECSRealTime)

• Virtual Documents Activities

• Virtual Agents Activities

Virtual Fields ActivityVirtual Fields Activity (previously known as LEI RealTime Activity or DECS RealTime Activity) provides access from a Domino application to asupported external data source, such as DB2. LEI, running on the DominoServer that is hosting the Notes application, intercepts and handles the Notesdatabase events. For example, when Notes or Web client users open, create,update, or save Notes documents, these events are acted upon, obtainingimmediate access from the Notes form to external data sources supported byAdvanced RealTime. You get the data immediately (dependent, of course,on network bandwidth and other factors that affect system resources).

Virtual Fields activity functionality includes features not available in theearlier RealTime Activity: support for computed subforms, options for newline delimiters, additional logging support, and support for procedurereturn parameters following insert and update operations. Output fromwrite operations allows results of write operations to be returned to fields inthe Notes document being monitored following insert and updateoperations.

Once a system administrator has created the Virtual Fields Activity, Notesusers can open, create, update or delete external, back-end data directly andtransparently through their familiar Notes client. By extension, Web clientsmay open the same Notes forms by accessing a Domino R6 server, andobtain access to supported external source data.

For example, if the external database to be queried or updated from theNotes form is DB2, Notes end-users may work with DB2 data as if it were inNotes. DB2 connectivity software is not required on the client system.Network access to the external data source is handled by the Domino servermachine, which contains the connectivity software for the external datasource, such as DB2. In addition, you have the option of storing retrieveddata to the Notes form, or to simply view the retrieved data.


In a Virtual Fields activity, for each record in the external system, Notescontains a place holder document or “key document” which contains thedatabase key value(s) needed to retrieve the data for that document. When the Domino application that uses the Virtual Fields Activity opens adocument, the key value in the key document is used to retrieve the virtualfields from the back end. To the application user, the data looks as though itis stored in the Notes document.

Virtual Documents ActivityThe functionality provided by a Virtual Documents activity is similar to that provided by a Virtual Fields Activity. The important distinction is thatVirtual Documents do not require the presence of key documents in a Notesdatabase. Instead Virtual Documents Activities store the NoteID (a Notesdocument unique identifier EIUNID and other pieces of information whichdetermine the document’s unique identity) in the external system itself.These values serve as the unique keys to the external system records.

As with all other Advanced RealTime functionality, a Virtual Documentsactivity is controlled by the LEI Administrator. You create a VirtualDocuments activity document that specifies which Lotus Connector to use to access the external system and which Notes database and form to monitor. The connection document for the selected external system mustbe created before you create the activity document.

When you start running a Virtual Documents activity, the activity monitorsa Notes form for an event, such as opening or creating a document that uses that Notes form. For example, when you open the document the data that populates the form is retrieved from the external data sourcespecified in the Virtual Documents activity document. When you create a new document, all data is stored in the external data source along withadditional information that maintains the integrity of the Virtual Documentfor the next time the Virtual Document is accessed by Domino. For example,the Notes form information is preserved so the correct form is used indisplaying the data the next time the Virtual Document is opened.

Virtual Agents ActivityA Virtual Agents Activity creates Domino Agents that run storedprocedures on the external system database. The agents that it creates are added to the Domino Agent menu. If the stored procedures requireparameters or if they return parameters, you must create Dominodocuments that hold these parameters; you then select the document or documents and run the agents against them.


Integrated Credentials DatabaseLike the Advanced RealTime Activities, the integrated credentials databaseis a recent addition to the LEI product offering. The integrated credentialsdatabase, available only for the three Advanced RealTime Activities,provides an additional and more robust security for associating a user IDand password to a specific external system database type, such as DB2,Sybase, or Oracle.

You can build one or more integrated credentials databases, and name themusing a meaningful naming convention, using the leicred.ntf template filesupplied with LEI. In this database, you associate a user ID, password, anddatabase type.

The three Advanced RealTime Activity Documents enable you to specifythat the credentials database is either used or not used for that specificactivity name. The Activity Document choices are “Integrated Credentials:Use Connector Credentials”, in which case the credentials database isignored, and “Integrated Credentials: Lookup Credentials”, which checksthe named credentials database to ensure that the current user ID andpassword have authority to the external system specified on the ConnectionDocument referenced on the active Activity Document. The ActivityDocument also provides a field in which you enter the file path to thecredentials database. Lastly, you can also specify that, in the event there is afailure accessing the named credentials database, the credentials of theActivity Document be used instead.

The Activity Document options that pertain to credentials checking aredescribed in the three Advanced RealTime Activity chapters of thisdocument — Virtual Fields, Virtual Documents, and Virtual Agents.

Setting Up and Using an Integrated Credentials DatabaseYou use integrated credentials to gain access to an external systemdatabase. To set up an integrated credentials document you must create aNotes document based on the credentials template leicred.ntf supplied withLEI. You can name the resulting .nsf file anything you like.

You can create and use a single integrated credentials database to containall connection credentials for all of your external systems. You can option-ally create multiple integrated credentials databases.


When you open the integrated credentials file, the following screen appears.

The fields in the integrated credentials database are described below:

• Allowed Readers — Specifies who has reader rights to this document. Ifa user is not listed, the document will not be visible to that user.

• Notes Identifier — Specifies the Notes Username of the user requestingthat the credentials be used. The Notes user ID is automaticallyobtained by LEI, entered in the field, and used as a search key. The IDvalue is derived from the Notes user ID editing the database. If addingthe ID of another user or server, edit this field using the same format.For example, if the Notes user ID shown in this field is CN=JohnDoe/OU=Widgets/O=HugeCompany and you wish to add credentialsfor Bob Smith who works in customer support, edit the field to CN=BobSmith/OU=Support/O=HugeCompany. The designations CN, OU, andO are built-in ID designations that correspond to the fully qualifiedNotes Domain name for a particular user or server. The designationsstand for Common Name, Organizational Unit, and Organization. Insome cases the OU designation may not apply. Consult your Dominosystem administrator if you are unclear of what to enter.

• Connector — Specifies the applicable connector name (for example,“Sybase” or “DB2”). If this field is filled in, it associates the credentialsto activities accessing this connector type (for example, to all Sybaseconnectors). This field is optional.

• External Server — Specifies the external server name. This field isoptional, however, if it is filled in, it restricts the credentials to activitiesaccessing servers with this name.


• External Database — Specifies the external database name. This field isoptional, however, if it is filled in, it restricts the credentials to activitiesaccessing databases with this name.

• External Userid — Specifies the user ID to use for connecting to theexternal system.

• Set Password — Specifies the password to use for connecting to theexternal system. The password will not be displayed in this form.

Integrated Credentials and Full Text IndexingIn order to perform full text indexing with Virtual Documents or VirtualFields in conjunction with integrated credentials, you must add the serverID to the integrated credentials database.

Integrated Credentials and Server to Server ReplicationIn order to perform server to server replication in conjunction withintegrated credentials, you must add the server ID of the server being repli-cated with to the integrated credentials database. For example, if you wantto replicate a Virtual Documents or Virtual Fields-enabled database onServer A to Server B, you must add Server B’s server ID to the integratedcredentials database on Server A.

Integrated Credentials in a Domino ClusterThe server IDs for all the servers in a Domino cluster that contain replicas ofthe Virtual Documents or Virtual Fields-enabled database must also beadded to the integrated credential database. For example, if a VirtualDocuments-enabled database on Server A has replicas on Servers B and C,and Servers A, B, and C are part of the same Domino cluster, the server IDsfor Servers B and C must be added to the integrated credentials database onServer A. If this is not done, the cluster replication process will fail to keepthe replicas synchronized.

Integrated Credentials and Virtual AgentsVirtual Agents only use integrated credentials for agent execution.

Integrated Credentials and Mapping to a Stored ProcedureWhen mapping to a stored procedure, the procedure name must beprefaced with the owner name in all instances where the owner name andthe name by which the user has logged in differ. For example, if you arelogged in as Emp54 and attempt to map to a stored procedure named abxowned by Emp98, you will receive a “Monitor failure error.”. To correctlymap to that procedure, rename it to Emp98.abx.


Integrated Credentials in HTTP and Notes ClientsThe following considerations are helpful when using HTTP and/or Notesclients to access an LEI-enabled database in conjunction with integratedcredentials.

• If your Domino server is configured to allow anonymous access viaHTTP, the user ID that will be looked up in the LEI credentials databasewill be “Anonymous.” In this case, to allow HTTP clients access youmust a) have an entry for “Anonymous” in the LEI credentials databasewith valid database credentials, or b) have the “Use connectorcredentials if user credentials unavailable” option is checked.

• If your Domino server is configured to deny anonymous HTTP access,and requires account information for HTTP access to the server, theuser ID that will be looked up in the LEI credentials database for HTTPclients will be the “Short name” for the account that you logged into theDomino server with initially. This name is listed in the server’s addressbook entry for the user, on the “Basics” tab under “Shortname/userID,” and is usually the first initial and last name of the user(such as “jsmith”). In this case you must have credentials entries for theshort name in your LEI credentials database to allow HTTP clientaccess.

• When a user accesses the database from a Notes client, the user ID thatwill be looked up in the LEI credentials database will be the full Notesuser ID for the user. In this case, you must have an entry for the fullNotes user name (such as “John Smith/CAM/Lotus”) in the LEIcredentials database to allow Notes client access.

Note If you are using integrated credentials with Virtual Documentsthrough an HTTP client, you also need a server credential document.

Note To provide the same access through an HTTP client and througha Notes client to a particular user, you must have credentials recordsunder both the user’s short name and the full Notes user name.


Command Line Execution of ActivitiesLEI allows activities to be executed from the system command line of themachine where an LEI server is running on a host. You might use thiscapability to execute LEIACT in response to specific database events.

Command syntax for starting an LEI Activity from the UNIX command lineis as follows:

leiact "Activity Name"

Command syntax for starting an LEI Activity from the Windows commandline is as follows:

nleiact "Activity Name"

Command syntax for starting an LEI Activity from the iSeries commandline is as follows:

CALL QNOTES/LEIACT 'Activity Name'

Note On iSeries, if you are authorized to run the QNOTES/LEIACTprogram, you can launch an LEI activity from the command line and it willrun under that process. Enter (in single quoted string) the name of the LEIActivity to be executed. The LEI Activity will access DB2/400 data underthe iSeries user profile registered in the DB2 connection and will accessNotes data under the user identified in KeyFileName. If the user ID inKeyFileName (resident in the notes.ini file) is password-protected, you willbe prompted for the password within your interactive iSeries process.

In all cases, Activity Name is the name of the existing LEI Activity that youwant to run. For example, the following NT command line entry wouldinvoke the quoted activity name:

nleiact "ABX Direct Transfer Activity"

General ConsiderationsWhen an activity is started from the system command line, it does notappear as running in the LEI Administrator or on the server console.However, logging still occurs.

The LEI server only runs activities that were scheduled from the Adminis-trator. Also, when an activity is running from an LEI server, it will not runsimultaneously on that, or any other, server until it has completed itscurrent execution. This is referred to as exclusive execution. In contrast,when an activity is started from the system command line, its executionmay be shared. This means that the activity may be run more than oncesimultaneously. At first this may not seem very valuable, but there arespecial cases where this capability is important. Performing searches for a


Web application or generating reports are two examples where sharedexecution is useful.

When running an activity from the command line, please note thefollowing:

• Any dependent activities listed in the Activity Document are notexecuted.

• The Activity Document’s document link to the log database is notupdated to point to the new log entry for that run.

Additional iSeries ConsiderationsLEIACT in the qnotes library is public *EXCLUDE and should remain so tosecure activities from being launched by unauthorized users.

Activity performance will be better when launched using the LEI server.You will see a log entry for all activities from a call to LEIACT, but thestatus of that execution will not be recorded in the LEI activity itself (underlast run status).

Data MappingDuring a Direct Transfer or Replication Activity, LEI maps columns in thesource and target databases in one of the following three ways:

• According to Field Name

• According to Field Position

• According to User Definition

Understanding how LEI performs field mapping is particularly useful whenconfiguring your Replication and Direct Transfer Activities.

Some Lotus Connectors have unique data mapping requirements. One suchexample is identity column support when using the Lotus Connector forDB2. Another example is stored procedures feature support for the LotusConnector for DB2.

Note For information about data types, see the “LEI and Data” appendix.For unique data mapping considerations that may apply to your specificLotus Connector, see the companion document Lotus Connectors andConnectivity Guide.


According to Field NamesData is transferred from a field in the source database to a field of the samename in the target. If the Activity’s command statement is a SQL query, youcan use column aliases to match the source field to the destination. Forexample, “SELECT empno employee” maps the empno field in the sourceto the employee field in the target.

Note The actual expression depends on the database SQL syntax.

According to Field PositionData in the first field of the source result set is copied into the first field ofthe target database, and so on. If the command statement in the Activityselects a subset of columns from the metadata, they will be treated as asimple incremental series starting with 1. The order in which the columnsare listed in the selection statement is the order in which they will be trans-ferred. The SQL statement “SELECT column6, column4, column7 FROMtable” maps column 6 of the source to field 1 of the target, column 4 to field2, and column 7 to field 3.

According to User DefinitionYou supply field names for both the source and target, and data fields aremapped in the order provided. For example, source fields listed as “A, B,C” and target fields listed as “X, Y, Z” result in source field A moving totarget field X, B to Y, and C to Z.

When Field Numbers Don’t MatchSince Replication does not require the same number of columns in bothdatabases, mismatching numbers of columns only affects Direct TransferActivities. The following occurs with these Activities:

• More columns in the source result set than in the target metadata —The transfer will fail and you’ll get an error message.

• Fewer columns in the source result set than in the target metadata —The transfer will succeed and the “orphan” columns in the target willbe filled with null values.


Stored Procedures and Output ParametersOutput parameter support enables LEI to return the results of a DirectTransfer or Virtual Fields activity, made using target stored procedures orERP calls, into the source database based on a condition in the targetdatabase. For example, you can write a stored procedure to perform aninsert into a DB2 table and then generate a status or confirmation number.The Direct Transfer Activity, using the stored procedure as the targetmetadata, then transfers the data to the external system (source connection).The data that is returned as a result set of the transfer is then directed to thefields in the source document that have been specified in the Stored Proce-dure Output Mapping — Source field of the Direct Transfer Activitydocument.

Note If the field names do not match exactly, you must explicitly mapthem in the field list.

The Direct Transfer Activity is the only LEI Activity that supports thiscapability. See the chapter entitled “Direct Transfer Activity,” for moreinformation about using this feature.

Currently, the Lotus Connector for DB2 and the Lotus Connector for SAP(available for purchase separately) are the only Lotus Connector types thatsupport stored procedures for output parameters.

A working knowledge of how your Connector supports output parametersfor stored procedures is required for using the LEI Direct Transfer Activityto create and use a target stored procedure. To learn more about how yourspecific Lotus Connector supports this functionality, see the specificConnector chapter in the companion manual Lotus Connectors and Connec-tivity Guide.

Note If the source or target metadata in an LEI Activity is designated as astored procedure, all declared parameters of that stored procedure must beaccounted for in the Activity (mapped or listed for return). If anyparameters declared in the stored procedure are missing from the Activity amessage is returned. For example, DB2 will return a message “SQL1109N-The specified dll <procedure> could not be loaded”. DB2 catalogues storedprocedures by name and number of parameters.


Example: Notes to DB2 Direct Transfer ActivityThis example uses DB2 output parameter code in a direct transfer betweena Notes database (source) and a DB2 database (target). Several values areobtained from the Notes database, such as employee name and hire date,and inserted into the SP_EMPdb2 table in the DB2 database. When theinsert function is complete, the stored procedure, named SP2, generates acurrent timestamp and assigns it to DATEPROC. DATEPROC is designatedas output so the values get passed back to the source (Notes) database.

1. Create the Notes Connection Document and the DB2 ConnectionDocument. For this example, the connection names are LEITEST andDB2v71 respectively.

2. Create the DB2 stored procedure. In this example, the stored procedurename is SP2. It is called as the target metadata on Direct TransferActivity Document.


3. Create and complete the top portion of the Direct Transfer ActivityDocument. In this example, the source and target connection names arespecified from step 1 above. Also, the stored procedure named SP2 isspecified in the Table Name field of the target connection. The form thatwill be updated by the stored procedure, in this example, SP_EMPdb2,is specified in the Form Name field of the source connection. The fieldmapping is done by name, as shown in the Field Mapping section of theActivity Document.

4. Complete the bottom portion of the Activity Document.

a. Enable the Target Metadata is Stored Procedure option in the TargetData section.

b. Enable the Accept Return Values into Source.

c. Enter DATEPROC as the Source and Target field in the StoredProcedure Output Mapping section.


5. Run the Activity. Example output is shown below. In this example,ENAME, EMPNO, MANAGER, and HIREDATE are inputs to thetarget database and DATE/TIME PROCESSED is the output from thetarget database.

Moving Text List Data over Different PlatformsIn Activities such as Advanced RealTime, Notes databases store all data inthe same canonical format (little-endian byte ordering) on all platforms.Notes data is automatically converted by LEI to the host platform’s byteordering format when read (for example, when the key field in the Notesform is accessed and used for record queries on the host back end system),and back to Notes canonical format when saved to a Notes form. (Compos-ite data is an exception: it is always left in canonical format).

System Planning Considerations: When moving data between Dominoservers and between Notes and other database systems, there is normallynot a problem. In the case, however, where data is moved from one Dominoserver to another through another DBMS using different LEI serverplatforms, multi-value types (text list, number list, datetime list) becomecorrupted. For example, you use an NT LEI server to move a text list fromNotes to DB2. If the data is moved from DB2 back to Notes through asecond LEI server running under Windows NT, there is no problem. But ifthe second LEI server runs on a UNIX platform, the text list data in thedestination database will be invalid.


Activity LoggingLogging information is available in all of the LEI activity views. The log liststhe time and date when an activity started and ran. It also contains informa-tion about any errors that occurred during processing of the activity.

To view the log for a specific activity, highlight that activity name in the LEIAdministrator and click the Current Activity Execution Log option in theaction bar.

Example output is shown below.

Note You can obtain the same output by clicking the View Log button inan active Activity Document.

To view the log history for all recent activities use the Log option in the LogHistory section of the Navigator.


Example output is shown below.

The very bottom section of the LEI Administrator can also be expanded todisplay information about active servers and jobs.


Chapter 6 Admin Backup Activity

This chapter provides information about the LEI Admin Backup Activity.

Introduction to the Admin Backup ActivityThe Admin Backup Activity creates a backup copy of your LEI Administra-tor database (decsadm.nsf) and, optionally, the LEI Script Vault database(leivlt6.nsf).

When to Use the Admin Backup ActivityUse the Admin Backup Activity when you want to create a safe backup ofthe LEI Administrator and associated documents.

You should use the Admin Backup Activity at regular intervals to ensurethat you have backup copies of existing LEI activities, connections, andconfigurations.

How to Create an Admin Backup ActivityThe steps below outline the general procedure for creating an AdminBackup Activity. See the other sections in this chapter for more informationabout the fields and options on the Admin Backup Activity Document.

1. Open the LEI Administrator database, decsadm.nsf.

2. Select Add Activity from the Administrator. Select Admin Backup fromthe resultant list.

3. Complete the required fields and select desired options in the AdminBackup Activity document.

4. Save the Activity Document.

85

Admin Backup Activity DocumentThe Admin Backup Activity Document is shown below. To create a newAdmin Backup Activity, click Add Activity and then select Admin Backupfrom the resultant list. To open an existing Admin Backup Activity, simplydouble-click its name in the Activities view.

Note See the chapter entitled “Introduction to LEI Activities” fordescriptions of the Activity Execution Options.


IdentificationUse the Name field to specify the unique Activity name. This name appearsin the Administrator’s list of defined Activities. It also appears in the LEIserver console’s list of defined Activities.

Backup OptionsThe backup options are described in the following table.

Specifies the file name of the LEI Script Vault copy (as a Notes.nsf file). If the database does not exist, the Activity will create it.Otherwise, the existing database will be overwritten. In addition,the file path can be assigned, for example, \qe\leivlt6b.nsf. Acopy of your leivlt6.nsf file will be created as this name.

A copy of your LEI Script Vault will be created with this name.

Note Only the scripts in the LEI Script Vault (leivlt6.nsf) thathave been created as Shared Agents are copied during thisActivity. This Activity does not copy private agents fromleivlt6.nsf to the target database. To ensure that your scripts arecopied to the target backup database, enable the Shared Agentoption in Domino Designer when you create your LS LSX scripts.

The path name specified must be relative to the data directory.

Leave this field blank if you do not want to back up the LEIScript Vault.

Script VaultTarget Database

Specifies the file name of the backup copy (a Notes .nsf file) ofyour LEI Administrator. If the database does not exist, LEI willcreate it. Otherwise, the existing database will be overwritten. Inaddition, the file path can be assigned, for example,\qe\leiback.nsf.

A copy of your LEI Administrator will be created with this name.

The path name specified must be relative to the data directory.

Leave this field blank if you do not want to back up the LEIAdministrator.

Target Database

Specifies the name of the Domino server where the backup copyof the LEI Administrator database and/or LEI Script Vaultdatabase will be stored.

You must specify a valid target server.

Target Server

DescriptionField

Note The LEI server must have manager access to the backup database inorder to delete the previous backup. Since the backup’s ACL is copied fromthe Administrator database’s ACL, the server needs manager access to theLEI Administrator.

Chapter 6: Admin Backup Activity 87

Chapter 7 Admin Purge Log Activity

This chapter provides information about the LEI Admin Purge LogActivity.

Introduction to the Admin Purge Log ActivityUse the LEI Admin Purge Log Activity to purge the LEI log database ofdocuments older than a user-specified number of days.

When to Use the Admin Purge Log ActivityYou should use the Admin Purge Log Activity for the LEI logs at differenttimes, depending on your situation. For example, if the LEI logs take up toomuch disk space, run this Activity regularly. This activity deletes existingLEI log documents.

How to Create an Admin Purge Log ActivityThe steps below outline the general procedure for creating an Admin PurgeActivity. See the other sections in this chapter for more information aboutthe fields and options on the Admin Purge Activity Document.


2. Select Add Activity from the Administrator. Select Admin Purge Logfrom the resultant list.

3. Fill in the required fields and select the desired options for the Activityin the Admin Purge Log Activity document.


Saving Selected Logs before PurgingTo save specific LEI logs, you must copy them to another Notes databasebefore running the Admin Purge Log Activity.

89

Admin Purge Log Activity DocumentThe Admin Purge Log Activity Document is shown below. To create a newAdmin Purge Log Activity, click Add Activity and then select Admin PurgeLog from the resultant list. To open an existing Admin Purge Log Activity,simply double-click its name in the Activities view.

Note See the chapter entitled “Introduction to LEI Activities” fordescriptions of the Activity Execution Options.



Purge Log OptionsThe Purge Log Options Older Than value specifies the age for log records.All documents older than the specified number of days will be deleted fromthe log. The number of days are counted from the time and date that theActivity is run. Each day is considered a 24 hour period.

Chapter 7: Admin Purge Log Activity 91

Chapter 8 Archive Activity

This chapter provides information about the LEI Archive Activity.

Introduction to the Archive ActivityAn Archive Activity moves data from one database to another. As recordsare moved into the target database, they are deleted from the source onerecord at a time.

The source data and target location are indicated by metadata name (forexample, table, form, and so on). Selection of documents to archive can bedone with a condition or relative time stamp.

The Archive Activity deletes the original records from the source database.

Note When using an Archive Activity, you cannot use an ODBCConnection Document if you are accessing a SQL Server 7 database. Toaccess the SQL Server 7 database, use an OLE DB Connection Documentinstead.

When to Use the Archive ActivityYou can use the Archive Activity to protect data on a regular basis, forexample:

• To place infrequently accessed data to a removable storage device tofree space on a system server

• To protect data when migrating from one database to another

• To create space on a full disk

93

Combining an Archive Activity with other ActivitiesYou can use the Archive Activity in combination with other LEI Activities.For example, you can combine the Archive Activity with a Polling Activityto Poll your system databases to determine when data was last accessed,and then archive it based on a specified date of its last access.

How to Create an Archive ActivityThe steps below outline the general procedure for creating an ArchiveActivity. See the other sections in this chapter for more information aboutthe particular fields and options on the Archive Activity Document.


2. Select Add Activity from the Administrator. Select Archive from theresultant list.

3. Fill in the required fields and select the desired options for the Activityin the Archive Activity document.

Note All connections referenced in the Activity should exist and bevalid. To test the validity of a connection, use CONTEST as described inthe Lotus Connectors and Connectivity Guide.



Archive Activity DocumentThe Archive Activity Document is shown below. To create a new ArchiveActivity, click Add Activity and then select Archive from the resultant list.To open an existing Archive Activity, simply double-click its name in theActivities view.

See the chapter entitled “Introduction to LEI Activities” for descriptions ofthe Activity Execution Options, Scheduling, and Other options.


Chapter 8: Archive Activity 95

SourceSource options are described below.

Specifies the metadata, based on the type of connectionchosen. For example, for a relational database themetadata is a Table, for a Notes database the metadata isa Form, and for a DB2 database the metadata is a view.

Form/Table/View Name

Specifies the name of the Source Connection.

Data is transferred from the Source Connection databaseto the Target Connection database. Each connectionidentifies the server and database with accessinformation. The Form/Table/View Name option (seebelow) identifies the metadata.

Connection

The Edit Connection button opens the named SourceConnection Document in Edit mode.

Edit Connection

DescriptionField

TargetTarget options are described below.

Specifies the metadata, based on the type of connectionchosen. For example, for a relational database themetadata is a Table, for a Notes database the metadata isa Form, and for a DB2 database the metadata is a view.


Specifies the name of the Target Connection.


Note To create a table in the target, you can enter aname in the Target Table Name field and in the ArchiveOptions section (see below), you can click “CreateTarget Metadata.”

Connection

The Edit Connection button opens the named TargetConnection Document in Edit mode.

Edit Connection

DescriptionField


MappingThe Mapping section of the Activity Document enables you to specify eithermanual or automatic field mapping. The default is manual mapping. Bothmapping styles are described here. For related information, see the DataMapping section in the “Introduction to LEI Activities” chapter.

Manual MappingThe manual mapping fields are described below.

Contains the connection-specific select statement to beexecuted. Some sample syntax is supplied by default.

Enter a command statement that identifies the data to beselected and transferred. The statement must conform to thesyntax rules of the database engine (for example, a SQL queryor Notes selection formula). A SQL query can be designed toselect data from one or more metadata objects.

Select Statement

Provides space for you to enter the exact field names in thetarget to be mapped to names in the source.

Target Columns

Provides space for you to enter the exact field names in thesource to be mapped to names in the target.

When you select a field in the source, the name automaticallypopulates the target field list. You can either leave the fieldname in the target list, or move/edit/delete it in the targetfield list.

To define your own field mappings, enter the names of thefields in the Source Field(s) and in the Target Columns in theproper mapping order. The first source field maps to the firsttarget field, the second to the second, the third to the third,and so on.

Source Field(s)

DescriptionField


Automatic MappingWhen you select the Automatic option, the automatic mapping fieldsappear. They are described below.

Contains the connection-specific select statement to beexecuted. Some sample syntax is supplied by default.


Select Statement

If you select Automatic, data is mapped from each sourcecolumn to the destination by position (first column to first,second to second, third to third, and so on) or by field name.

Selecting this option displays the following two options.

wwww By Name — Automatically performs all mapping from thesource to the target based on an exact name matchbetween the two.

wwww By Position — Automatically performs all mapping fromthe source to the target based on an exact position match(left to right, top to bottom) between the two.

Automatic

DescriptionField

Archive Selection OptionsWhen you select the Archive Options tab and the Selection Options tab, thefollowing options appear.


Optionally contains a conditional clause, written in thelanguage of the source connection, to determine whichrecords are to be archived. This allows you to useconditional criteria to choose specific record names in atable.

Conditional Archive

Specifies the minimum age of records to be timestamped.For example, to specify that all records older than 30 daysbe archived, enter 30 in this field.

Timestamp Cutoff inDays

Specifies the name of the field that contains the timestampvalues that LEI will use to measure date and time from.

Note If using a DB2 external system, the DB2 columnselected for the Timestamp Field must be of typeTIMESTAMP, not DATE.

Timestamp Field

When you enable the Timestamp Archiving option, thefollowing Timestamp Field and Timestamp Cutoff in Daysoptions appear.

Timestamp Archive

DescriptionField

Archive Precision OptionsWhen you select the Archive Options tab and the Precision Options tab, thefollowing options appear.

Specifies that LEI truncate text data when necessary toconform to field lengths in the target database. Because ofperformance penalties, this option does not affect numbersbeing written.

Truncate Data WhenNecessary

Specifies that LEI not report loss of numerical or datetimeprecision as a result of the transfer.

Allow Precision LossOnly

Specifies that LEI write an error to the log for any data thatis lost as a result of the transfer and that it then terminatethe transfer.

Generate Error forany Data Loss

DescriptionField


Archive Target Data OptionsWhen you select the Archive Options tab and the Target Data Options tab,the following options appear.

Selecting Create Target Metadata enables LEI to create anew metadata in the database identified in the target tohold the data being transferred if one does not already exist.In creating new metadata, LEI attempts to match the sourcemetadata as much as possible.

If you do not select Create Target Metadata, LEI displays anerror message if a specified target table does not exist.

Note When archiving data from a Notes source with“Create Target Metadata” selected, Notes Text fields createcharacter objects of size 64996 bytes (the maximum size of aNotes Text field) in some RDBMS external systems.

Existing Data OptionsCreate TargetMetadata

DescriptionField


Chapter 9 Command Activity

This chapter provides information about the LEI Command Activity.

Introduction to the Command ActivityA Command Activity executes operating system, database, and SQLcommands.

In order to execute an operating system command, select No Connector andenter the command as it would be entered at an operating system commandprompt.

To execute a database or connection-specific command, select the appropri-ate Connection Document.

When to Use a Command ActivityYou should use the Command Activity when you need to execute a specificcommand either on a connected database or on the operating system onwhich the LEI server is running.

You can use the Command Activity to execute an SQL statement on asupported connection or execute an operating system command.

How to Create a Command ActivityThe steps below outline the general procedure for creating a CommandActivity. See the other sections in this chapter for more information aboutthe particular fields and options on the Command Activity Document.


2. Select Add Activity from the Administrator. Select Command from theresultant list.

3. Fill in the required fields and select the desired options for the Activityin the Command Activity Document.

101

Note All connections referenced in the Activity must exist and bevalid. To test the validity of a connection, use CONTEST as described inthe Lotus Connectors and Connectivity Guide.


Command Activity DocumentThe Command Activity Document is shown below. To create a newCommand Activity, click Add Activity and then select Command from theresultant list. To open an existing Command Activity, simply double-clickits name in the Activities view.


Note See the chapter entitled “Introduction to LEI Activities” fordescriptions of the Activity Execution Options, Scheduling, and Otheroptions.


ConnectionThe Connection Name field entry specifies the name of the connection. Thecommand statement will be executed against this connection. The connec-tion identifies the server and database along with required accessinformation.

To execute a command in the local operating system, specify no connection.

The Edit Connection button opens the named Connection Document in Editmode.

Note When using no connection (for example when submitting an OScommand), any command that takes input must have that input redirectedfrom a file. If not, then this Command Activity will wait for input at the LEIconsole, and the Activity will seem to hang. For example, while thecommand “del *.*“ on NT will hang as it waits for confirmation, thecommand “del *.* < input.txt”, where input.txt contains a “y” followed by anew line, will process correctly because the confirmation has beenredirected to come from the file rather than from user input (stdin).

CommandThe Command Statement entry specifies the Connector-specific (oroperating-system specific, when no Connector is selected) statement thatidentifies the action to be performed. The statement must conform to thesyntax rules of the database engine or local machine (for example, a SQLquery or Notes selection formula).

Chapter 9: Command Activity 103

Command Activity ExamplesFollowing are some examples that illustrate how to use the CommandActivity.

Command Activity Using SQLThis Command Activity inserts a row in a DB2 table. This example showshow you can manipulate data in a relational database using a SQL state-ment within a Command Activity.


Command Activity Using a Notes AgentThis example runs a Notes agent using the EXECUTE command statement.Notice that no quotes are required around the name of the Notes agent.

The EXECUTE command statement is used to run a single Notes agent. Nocommand parameters are used.

The agent shown in the next figure, as it appears in Domino Designer, isexecuted by the above Command Activity. To open Domino Designer andan Agent view from within LEI, choose Create - Design - Agent from theNotes top bar.

Note This particular agent is designed to run against “All documents inthe database.” The only other valid document selection option for an agentis “Run Once.” Because agents cannot be view-based, the Domino Designeroptions “Run on selected documents in view” and “Run on all documents


in view” are not supported. See the “Lotus Connector for Notes” chapter inthe companion Lotus Connectors and Connectivity Guide for more informationabout Activity Command statements.


Command Example Issuing Operating System CommandsThis example executes an operating system-specific command. TheCommand Activity does not require that you specify a Connection Name.This allows you to enter command statements directed at the system.

Another command statement example is shown below:

del /q V:\SalesByMonth\June\*.*

You do not need to specify a File connection to use this type of commandstatement.

Note Inadvertently inserting a space in a file path can corrupt the Dominoand LEI installations by deleting the notes.ini file.


Chapter 10 Direct Transfer Activity

This chapter provides information about the LEI Direct Transfer Activity.

Introduction to the Direct Transfer ActivityA Direct Transfer copies data from one database to another. The data to betransferred is identified by a statement, for example a SQL query or Notesselection formula.

You can start a Direct Transfer Activity either by clicking the Start buttonon an open Direct Transfer Activity Document, highlighting the Activityname in the Activity View of the Administrator and clicking Start, or byscheduling the Activity using LEI scheduling options.

When to Use a Direct Transfer ActivityYou should use the Direct Transfer Activity when you want to move datafrom one database to another. You can also combine a Direct TransferActivity with a Polling Activity in order to perform the data transfer when aspecified condition is met.

In some situations, you can enable output parameter support in order toupdate a field in the data source when the data transfer to the target issuccessful.

How to Create a Direct Transfer ActivityThe steps below outline the general procedure for creating a Direct TransferActivity. See the other sections in this chapter for more information aboutthe particular fields and options on the Direct Transfer Activity Document.


2. Select Add Activity from the Administrator. Select Direct Transfer fromthe resultant list.

109

3. Fill in the required fields and select the desired options for the Activityin the Direct Transfer Activity Document.



There is an example of building a Direct Transfer Activity in the “Tutorials”appendix.

Direct Transfer Activity DocumentThe Direct Transfer Activity Document is shown below. To create a newDirect Transfer Activity, click Add Activity and then select Direct Transferfrom the resultant list. To open an existing Direct Transfer Activity, simplydouble-click its name in the Activities view.

Note See the chapter entitled “Introduction to LEI Activities” fordescriptions of the Activity Execution, Scheduling, and Other options.



SourceSource options are described below.

Specifies the metadata, based on the type of connectionchosen. For example, for a relational database themetadata is a table, for a Notes database the metadata is aform, and for a DB2 database the metadata is a view.

Form/Table/ViewName

Specifies the name of the Source Connection.


Connection Name

The Edit Connection button opens the named SourceConnection Document in Edit mode.

Edit Connection

DescriptionField

TargetTarget options are described below.

Specifies the metadata, based on the type of connectionchosen. For example, for a relational database themetadata is a table, for a Notes database the metadata isa form, and for a DB2 database the metadata is a view.


Specifies the name of the Target Connection.

Data is transferred from the Source Connectiondatabase to the Target Connection database. Eachconnection identifies the server and database withaccess information. The Form/Table/View Nameoption (see below) identifies the metadata.

Connection Name

The Edit Connection button opens the named TargetConnection Document in Edit mode.

Edit Connection

DescriptionField

Chapter 10: Direct Transfer Activity 111

MappingThe Mapping section of the Activity Document enables you to specify eithermanual or automatic field mapping. The default is manual mapping. Bothmapping styles are described here. For related information, see the DataMapping section in the “Introduction to LEI Activities” chapter.


Contains the connection-specific select statement to beexecuted. Some sample syntax is supplied in the pop-up help.


Select Statement

Provides space for you to enter the exact field names in thetarget to be mapped to names in the source.

Target Columns

Provides space for you to enter the exact field names in thesource to be mapped to names in the target.

When you select a field in the source, the name automaticallypopulates the target field list. You can either leave the fieldname in the target list, or move/edit/delete it in the targetfield list.

To define your own field mappings, enter the names of thefields in the Source Field(s) and in the Target Columns in theproper mapping order. The first source field maps to the firsttarget field, the second to the second, the third to the third,and so on.

Source Field(s)

DescriptionField


Note If you select to “Create Target Metadata” and you have aNotes/Domino database as a source and you have a RDBMS externaldatabase, such as DB2, as the target, the Notes Text fields create characterobjects of size 64996 bytes in the target database. To limit the size of textfields, edit the Notes Connection document option “Maximum Length forText Data.”


Contains the connection-specific select statement to beexecuted. Some sample syntax is supplied in the pop-up help.


Select Statement

If you select Automatic, data is mapped from each sourcecolumn to the destination by position (first column to first,second to second, third to third, and so on) or by field name.

Selecting this option displays the following two options.

wwww By Name — Automatically performs all mapping from thesource to the target based on an exact name matchbetween the two.

wwww By Position — Automatically performs all mapping fromthe source to the target based on an exact position match(left to right, top to bottom) between the two.

Automatic

DescriptionField

Direct Transfer OptionsThe Direct Transfer Options provide selections for data handling during theActivity. For example, enabling output parameters for stored procedures isaccomplished using this portion of the Activity Document. Each of theavailable options are described in the following tables.

Precision OptionsWhen you select the Direct Transfer Options tab and the Precision Optionstab, the following options appear.


Specifies that LEI truncate text data when necessary toconform to field lengths in the target database. Because ofperformance penalties, this option does not affect numbersbeing written.

Truncate Data whenNecessary

Specifies that LEI not report loss of numerical or datetimeprecision as a result of the transfer.

Allow Precision LossOnly

Specifies that LEI write an error to the log for any data thatis lost as a result of the transfer and that it then terminatethe transfer.

Generate Error forany Data Loss

DescriptionField

Source Data OptionsWhen you select the Direct Transfer Options tab and the Source DataOptions tab, the following options appear.

Selecting the Source Metadata is Stored Procedure optionenables you to call a stored procedure from the sourcedatabase as a means of obtaining a result set. This feature isavailable only for Connectors that support storedprocedures that can return result sets or output parameters.The stored procedure can never have input parametersdeclared.

The Select Statement will not be used when this option isenabled.

Source Data

DescriptionField


Target Data OptionsWhen you select the Direct Transfer Options tab and the Target DataOptions tab, the following options appear.

continued

When selected, this option prompts for a key field to use tocheck for records to update.

Insert Options: TryUpdate Before Insert

Checking this box causes all the data in the destinationmetadata to be deleted before the new data is transferred.Note that even if the transfer fails to complete successfully,the data already has been deleted from the target and will belost.

If this option is not checked, the transferred data isappended to the existing data in the target.

Existing DataOptions: OverwriteExisting Data

LEI will create a new metadata in the database identified inthe Target Connection to hold the data being transferred ifone does not already exist. In creating a new metadata, LEIwill try to match the source metadata as much as possible.

If the source table contains no records, the Direct TransferActivity will not transfer the table. To transfer the table, incases where all table records contain NULL entries, add onerecord to the table and then perform the Direct TransferActivity.

Note When transferring from a Notes source with “CreateTarget Metadata” selected, Notes Text fields create characterobjects of size 64996 bytes (the maximum size of a NotesText field) in some RDBMS external systems. To limit thesize of text fields, edit the Notes Connection documentoption “Maximum Length for Text Data.”

Existing DataOptions: CreateTarget Metadata

DescriptionField


continued

If you have enabled “Target Metadata is Stored Procedure”,this option appears. This option enables the return ofparameters from the stored procedure to fields in the sourceconnection.

For DB2 users, enabling this option opens a user-definablefield mapping section. Use this field mapping section to mapfields in the source connection (metadata) to target fieldsdesignated as output parameters declared in the storedprocedure.

For SAP users, enabling this option opens a user-definablefield mapping section. Use this field mapping section to mapfields in the source connection (metadata) to either targetfields designated as export parameters or to the result setreturned by the stored procedure.

Note Each output parameter fetched affects the activity’slogged fetch count. The fetch count value is the total numberof records fetched for the overall activity. Since the outputsfor each procedure call needed to be fetched, the activity logwill display twice as many fetches as expected: half from thesource and half from the target. This is the correct andintended behavior.

You can map the source fields with the stored procedureoutput parameters in the Stored Procedure Output Mappingsection.

Accept OutputParameters intoSource

Specifies that trailing spaces in a text field not be trimmed.The default behavior is to trim trailing spaces.

Options: DisableTrimming of TextTrailing Spaces

Enable this option to have the activity log all insertion errorsand continue with the transfer.

Options: Continueon Insert Errors

When set, the target metadata indicates a stored procedureto execute. The fields being transferred become inputparameters to the stored procedure with the field names asparameter names.

If selected, the Accept Output Parameters into Source menuoption appears.

Options: TargetMetadata is StoredProcedure

The target key field is used to find the data record in thetarget, and, if found, the record will be updated (whether itchanged or not) on the destination.

If a record from the source (based on key field) does notmatch with a record in the target, then that record will beinserted into the target as a new record.

Insert Options:Target Key Fields for Update

DescriptionField


Lists parameters in the target connection that will returndata to the source. The first parameter listed will map to thefirst source field listed and so on.

Stored ProcedureOutput Mapping:Target Parameters

Lists the fields in the source connection that will receive thestored procedure output. The first source field listed willmap to the first output parameter listed and so on.

Stored ProcedureOutput Mapping:Source Fields

DescriptionField

Performance OptionsWhen you select the Direct Transfer Options tab and the PerformanceOptions tab, the following options appear.

Specifies the total number of records that you want thisActivity to transfer. Zero (0) equals no limit.

Maximum Number ofRecords to Transfer

Enables buffering of records prior to transfer. By default,one record is transferred at a time.

For databases and connections that support arraytransfers, this number defines the number of records totransfer at a time. Transferring multiple records at a timecan increase performance, but only with databases thatsupport the feature.

Note If the Target Metadata is a Stored Procedureoption is enabled, the only valid entry in this field is 1.

Number of Records toTransfer Concurrently

DescriptionField


Direct Transfer Activity ConsiderationsThis section describes considerations for using the Direct Transfer Activity.

Using Stored Procedures and Output ParametersConsiderations for using stored procedures and output parameters arepresented below.

• Currently, the Lotus Connector for DB2 and the Lotus Connector forSAP (available for purchase separately) are the only Lotus Connectortypes that support stored procedures for output parameters.

• If the source or target metadata in an LEI Activity is designated as astored procedure, all declared parameters of that stored proceduremust be accounted for in the Activity (mapped or listed for return). Ifany parameters declared in the stored procedure are missing from theActivity, a message will be returned. For example, DB2 will return a“SQL1109N - The specified dll <procedure> could not be loaded” (DB2catalogues stored procedures by name and number of parameters.) Seethe “Lotus Connector for DB2” chapter of the Lotus Connectors andConnectivity Guide for more information.

• When the Source or Target is a stored procedure, the PerformanceOption “Number of Records to Transfer Concurrently” only supportsthe default of one record.

• Fields and stored procedure parameters are internally associated byname, so fields and parameters should always be explicitly mapped inthe appropriate mapping sections. When using a stored procedure withoutput parameters as the target of a Direct Transfer, the AutomaticField Mapping By Position option should not be used.

For an example of how to use stored procedures for output parameters, seethe “Introduction to LEI Activities” chapter of the IBM Lotus EnterpriseIntegrator Activities and User Guide.

Using the Lotus Connector for NotesWhen transferring from a Notes source with the Data Option “CreateTarget Metadata” selected, Notes Text fields create character objects of size64996 bytes (the maximum size of a Notes Text field) in some RDBMS exter-nal systems (DB2 for example). To limit the size of text fields, edit the NotesConnection Document option “Maximum Length for Text Data.”


Using the Lotus Connector for File System

• If the Source or Target Connection of a Direct Transfer is a Fileconnection and Automatic Field Mapping by Position is selected, thepositional order of the File fields is as follows:

Filename

Contents

Timestamp

Size

• If the Source Connection of a Direct Transfer is a File Connection, youcan leave the select statement blank. The activity will proceed withoutan error as though the select statement had read as follows:

select *.*

Using Oracle or ODBC to Create Target MetadataIn order to use a Direct Transfer Activity to create metadata that containsmore than one column of type LONG VARCHAR (ODBC type that maps toOracle’s LONG) you must use the Lotus Connector for Oracle 7, instead ofthe Lotus Connector for ODBC. Oracle does not support more than onecolumn of type LONG in a table or in an SQL statement.


Chapter 11 Polling Activity

This chapter provides information about the LEI Polling Activity.

Introduction to the Polling ActivityPolling is a way of monitoring conditions in a database and triggering asubordinate Activity(s) when those conditions are met. As soon as thecondition is met, the subordinate Activity(s) are executed. SubordinateActivities are defined in their own Activity document and are called by thePolling Activity.

The connection used by the Polling Activity must remain available for aslong as the activity is to run. LEI will make one, single attempt to reestab-lish a closed connection. If this attempt fails, the Activity will end in error.The Polling Activity does not reestablish a closed connection to a datasource. For example, if you have configured Sybase to time out its connec-tion after 10 minutes of inactivity, but your Polling Activity has a pollinginterval set to 15 minutes, the Sybase connection may time out and closebefore the Polling Activity checks the connection. in this case, the PollingActivity would fail.

When to Use the Polling ActivityYou should use the Polling Activity when you need to execute some actionwhen another action or event occurs or is encountered. For example, yourHuman Resources department may use an Oracle database for employeeinformation. You may need to maintain this same information in a Notesdatabase so that Sales and Marketing departments can access it. You coulduse a Polling Activity to check the Oracle database for new or changedrecords. When the Polling Activity detects such an event, it would trigger aReplication Activity to copy the changed data to the Notes database.

Note The Polling Activity can run more than one activity at a time (forexample, a Replication Activity and a Direct Transfer Activity). However,when you start the Polling Activity, the specified (subordinate) activities arenot run in the sequence in which they are specified. If you want to run thespecified activities in a given sequence, use the “Dependent Activities” field

121

in the General Options section of the activity document, see the chapterentitled “Introduction to LEI Activities” for more information about theGeneral Options.

How to Create a Polling ActivityThe Polling Activity Document contains the information needed to executesubordinate activities, including:

• Condition under which the subordinate Activities (the Activities toexecute) will be run

• Scheduling and polling frequency

• Names of subordinate activities to be executed

Note Information about how to access the polled database must be definedin a Connection Document before the Polling Activity is created. Allsubordinate Activities must also be defined (in their own ActivityDocuments) before you can create a Polling Activity.

The steps below outline the general procedure for creating a Polling Activ-ity. See the other sections in this chapter for more information about theparticular fields and options on the Polling Activity Document.


2. Select Add Activity from the Administrator. Select Polling from theresultant list.

3. Fill in the required fields and select the desired options for the Activityin the Polling Activity Document.



There is a complete example of building a Polling Activity in the“Tutorials” appendix.


Polling Activity DocumentThe Polling Activity Document is shown below. To create a new PollingActivity, click Add Activity and then select Polling from the resultant list.To open an existing Polling Activity, simply double-click its name in theActivities view.

You can either request that polling occur based on a trigger statement orthat polling occur based on a timestamp field; the two polling types aremutually exclusive. To request trigger-based polling, specify an appropriatevalue in the Table and Trigger Statement fields. To request timestamp-based polling, enable the Timestamp Polling option and then specify anappropriate Timestamp field value.

Chapter 11: Polling Activity 123



ConnectionThis section provides information on the source of the data to be polled.Connections and subordinate Activities must be created before they can beused in a Polling Activity Document.

continued

Specifies the name of the connection containing thedatabase to be polled.

When you specify a Connection Name, the EditConnection button appears.

Connection Name

Opens the specified Connection Document (using theConnection Name below) in Edit mode.

The Edit Connection button is only available after youspecify a Connection Name.

Edit Connection

DescriptionField


Enabling this option clears the stored timestamp value forthis polling activity, causing all activities specified forpolling to run the next time that this activity is run. Aconfirmation screen appears enabling you to choose Yes toContinue or No to Cancel.

Reset Timestamp

Specifies a data field that contains the datetime of interest.The Polling Activity will poll this datetime field for avalue between the last poll datetime and the currentdatetime. If records fit this criteria, the Activities chosen in“Activities to Execute” will run. This field only appearswhen you select Enable Timestamp Polling.

The timestamp field value is only used when you requesttimestamp-based polling. It is not used when you requesttrigger-based polling.

Note If using a DB2 external system, the DB2 columnselected for the Timestamp Field must be of typeTIMESTAMP, not DATE.

Timestamp Field

Check the Enable Timestamp Polling option to requesttimestamp-based polling and display the Timestamp Fieldand the Reset Timestamp options.

The initial timestamp polling value is set to “01/01/000112:00:00 AM”, causing all activities specified for polling torun when the activity is started.

Timestamp Polling

Specifies the connection-specific trigger statement thatyou want to execute. A sample trigger statement is shownbelow:

select * from SYM_TEST_SYBASE

In this case, the trigger will be TRUE if any rows exist inthe table.

The trigger statement identifies the condition that willcause the Polling Activity to place subordinate activities ina queue for execution. The trigger statement is satisfiedwhen it produces a result set containing at least onerecord. This is considered a successful poll.

The trigger statement is only used when you requesttrigger-based polling. It is not used when you requesttimestamp-based polling.

Trigger Statement

Specifies the metadata for trigger-based polling, based onthe type of connection chosen. For example, in a relationaldatabase the metadata is a table, in a Notes database themetadata is a form, and in a file the metadata is asubdirectory.

Table

DescriptionField


DefinitionWhen you select the Definition tab, the following options appear.

continued

Specifies the list of subordinate Activities to execute when theresult of the Trigger Statement is true.

The activities are listed alphabetically for convenience and donot reflect any execution sequence. To control the dependence ofone activity on the completion of another activity, use the“Dependent Activity(s)” field in the General Options section ofeach activity.

The Polling activity will run the specified activitiesindependently of the activities’ schedules. Specifying an Activityhere will have no effect on its own scheduling or whether it canbe run using the Start! button.

Note You do not need to enable Scheduling on the subordinateActivity Document in order for that activity to be run from thePolling Activity.

Activities toExecute

Specifies, in number of seconds, how often the database is to bepolled to check for the condition defined in the TriggerStatement.

The polling only occurs within the window of time defined inthe Scheduling section of this Activity Document. See the “Noteson Polling Activity Scheduling” section later in this chapter.

PollingFrequency

DescriptionField


Commit Post Statement — For connections that support aCommit Action, this commits the Reset Trigger statementfollowing each execution.

Commit Options

Specifies when to reset: either before or after the activity hasstarted. You can also choose to have the statement execute afterthe subordinate activity has completed — see Note below.

wwww Execute before Activities — Executes the Reset Trigger beforethe subordinate activities are started.

wwww Execute after Activities — Executes the Reset Trigger after thesubordinate activities are started.

Note If you also enable Execute Synchronously, then thetrigger will reset the activity after the activity completes. If youdo not also enable Execute Synchronously, then the trigger willonly reset after the activity starts, not after the activity completes.

Reset TriggerExecution

Specifies an optional statement for resetting a trigger conditionafter a successful poll has occurred. It specifies the optionalstatement to execute after a successful poll. This statement canbe used to reset the condition that caused the poll to succeed.

For Notes, the statement must be a formula agent using thefollowing formula:

Execute agentname

In Domino Designer, select Formula when you create the agent.You must also select the “All documents in database” option.

When you enter a value in the Reset Trigger Statement field, theReset Trigger Execution and Commit Options fields appear.

Reset TriggerStatement

Enabling the Execute Synchronously setting suspends pollingwhile subordinate activities are executed. By default, this optionis not checked and polling is not suspended while subordinateactivities are executed.

When polling is suspended while the subordinate activities areexecuted, polling will not resume if a subordinate activitycannot complete for any reason (for example, the server thatwas supposed to run it is not up). In this case, the PollingActivity will remain suspended until closed manually.

Note If you enable both Execute Synchronously AND ResetTrigger Execution: Execute after Activities, the trigger will resetafter the activity completes.

SynchronousSetting

DescriptionField


Error Handing OptionsWhen you select the Error Handing Options tab, the following optionsappear.

Specifies the number of times the Activity will pollsuccessfully before terminating. A value of 0 specifies thatthere is no limit to the number of times polling can occur.

Maximum Event Count

Ignore Polling Errors — Check this option to continuepolling if the Trigger Statement returns an error (otherthan a statement that the connection has been lost).

On Polling Error

DescriptionField

Considerations for Polling Activity SchedulingThe following considerations provide practical insight into schedulingPolling Activities.

• A Polling Activity is an ongoing activity, unlike batch activities such asDirect Transfer or Replication.

• Polling Activities should always be scheduled with Start and Stoptimes. If you use the Start and Stop time specifications, you do not needto enable the Restrict to Schedule option.

• Polling Activities are only scheduled when they are run from the LEIAdministrator.

• If a Polling Activity is executing a poll at the exact Stop time, it willcomplete that poll. If that poll is successful, the Polling Activity willthen run the subordinate activities.

• Polling Activities may have dependent Activities as well as subordinateActivities. Dependent Activities are only run once the Polling Activityends in one of the following ways:

• The schedule expires

• The Polling Activity is shut down by the user

• The specified number of successful polls has been made


• The Maximum Duration setting is designed to halt a single Activity thathas been executing for too long and that may actually be hung. Tospecify that an Activity poll for a specific duration, such as 45 minutesor from 6:00 to 6:45, use Start and Stop time specifications on theActivity document.

• When a Polling Activity is started, it makes a persistent connection tothe external system which is not terminated until the Activity is closedby either the user or the schedule.

• Even though the Polling Activity is typically only reading an externaldata source, the Read transactions must be committed. A Read is notcommitted by default. This may mean that other processes or users maybe denied access to the table until the Read is committed. You shouldissue a Commit after every transaction in the Connection Document,including Read transactions.

Example: Scheduled Polling ActivityIn this example, a user wants to do the following:

• Poll every 60 seconds from 6:00 PM to 6:45 PM.

• After one successful poll, execute another Activity.

To accomplish this objective, set the following values on the Polling Activitydocument:

• Run at Times: 6:00 PM - 6:45 PM

• Maximum Duration [ ]

• Repeat Interval [60] seconds


Chapter 12 Virtual Fields Activity

There are three Advanced RealTime Activities in LEI.

• Virtual Fields (previously known as LEI RealTime or DECS RealTime)

• Virtual Documents

• Virtual Agents

This chapter provides information about the Virtual Fields Activity.

Introduction to Virtual Fields ActivitiesLEI activities can monitor Notes forms. LEI connects these forms to externaldata sources (such as DB2) through Lotus connectors. Once a systemadministrator has created a Virtual Fields activity (previously known as theLEI RealTime Activity), you can open, create, update or delete externalsystem data directly and transparently through their Notes client. Byextension, Web clients can open the same Notes form that the activitymonitors by accessing a Domino server and obtain access to supportedexternal source data.

For example, if the external database to be queried or updated from theNotes form is a DB2 database, Notes end-users may work with DB2 data asif it were in Notes. DB2 connectivity software is not required on the clientsystem, however it must be installed on the Domino server machine.Network access to the external data source is handled by the Domino servermachine, which contains LEI connectivity software for the external datasource, such as DB2.

Virtual Fields functionality includes the following features not available inthe earlier RealTime activity:

• Support for computed subforms, options for new line delimiters

• Integrated credentials

• Support for procedure return parameters following insert and updateoperations

Output from write operations allows results of write operations to bereturned to fields in the Notes document being monitored following insert

131

and update operations. One activity can monitor all forms in a database,making it possible to perform a generic lookup of a given field.

OverviewIn Virtual Fields activities, Notes documents still exist for every data setpresented to the user. Virtual Fields activities simply add external systemdata to an existing document.

In the simplest Virtual Field scenario, the Notes document contains only thekey value necessary to retrieve the external system data. These Notesdocuments are referred to as “key” documents (in previous documentationthese were referred to as “stub” documents). While the Notes document canbe a simple key document, it can also contain additional fields. Any fieldnot mapped to external system data is saved in the Notes document.

Each Virtual Fields activity monitors a specific Notes form where themetadata is defined. Metadata is the list of fields in the Notes form that aremapped to a list of fields in the external data source during data query orupdate. You must map the key fields in the external data source to thecorresponding fields in the Notes form using the Virtual Fields activity. TheVirtual Fields activity requires key documents (referred to as “stubdocuments” in previous releases) in the Notes database to function. Thesekey documents must be initialized once and only once in the Virtual Fieldsactivity. See below, “How Key Documents Work,” for more information.

In addition, Virtual Fields activities can invoke external system storedprocedures to produce the data to display in the form.

The use of Virtual Fields in combination with Virtual Documents isdocumented in the “Using Virtual Fields with Virtual Documents”appendix.

Multiple Virtual Fields Activities and Monitor OrderVirtual Fields activities operate at the field level. You can have multipleVirtual Fields activities monitoring the same form in a Notes document, buteach activity is responsible for a subset of the fields on a form. For example,if any of the Virtual Fields activities is not running, the document formcontains all the fields, but only the fields for the stopped Virtual Fieldsactivities will be blank. In brief, you can use one or more Virtual Fieldsactivities to monitor a form in a Notes document, as long as you makeproper use of monitor order where appropriate.

Using monitor order you can have one activity that uses, for example,empid as a key to retrieve employee data, including the job ID. The job ID,could in turn be used as a key in another activity to retrieve the job title,description, salary range, and so on. In short, you do a lookup that gets akey to do the next lookup, and so on.


In summary, one or multiple external sources may be accessed from theNotes form. A single external data source definition (connection document)indicates the data source to connect to and the metadata to use. ManyVirtual Field activities can be used to monitor a single form; each of theseaccess data from multiple external data sources. The ability of Virtual Fieldsto aggregate information from multiple tables onto a single Notes documentform is one reason why you might want to use a Virtual Fields activityrather than a Virtual Documents activity.

In addition, you have the option of storing retrieved data to the Notes form,or you can simply view the retrieved data. See Data Storage under “GeneralOptions” later in this document.

How Key Documents WorkWhen you initially create a Virtual Fields activity for a database which hasexisting records, you use the “Initialize Keys” option to populate the Notesdatabase with one “key document” for each external system record. TheseLEI initialized “key documents” contain the key value(s) that are mappedto the external system table and that you specified in the activity document.These key(s) are used to do the lookup into the external system table. Whenthe Notes document is opened, the key(s) in the “key documents” are usedto fetch external system data to populate the rest of the fields. InitializingKeys is a onetime task that is used to populate a new Notes database withthe necessary key documents. Once you have initialized keys, the way toincorporate additional data that is added to the external source fromoutside of Notes and Domino is to use a Replication activity.

When you create a new document through a Notes client, a “keydocument” is created and saved with the key field value(s).

In the simplest case, all of the data resides in an external database and theNotes document only holds the lookup key, the note is really a place holder,or key document. However, the “key document” can be much more thanjust a container to hold the key(s). It can be used to contain other data inaddition to the data stored in the external system. Any fields on the formwhich are not mapped to an external system field in the activity documentwill be stored in the “key document.” In addition, in the Virtual Fieldsactivity document, mapped fields can be specified as fields that should besaved in the “key document”. In any case, all mapped field values arestored in the external data source.

For example, you can construct a form, monitored by a Virtual Fieldsactivity, that displays, employee history, payroll data, and personalinformation. In this situation, assume that the employee data and personalinformation is stored in a Notes database (nsf), and the payroll departmentinformation is stored in a DB2 database. In this case, the “key document” isonly a “key” in the sense that the employee ID, for example, is used to fetch

Chapter 12: Virtual Fields Activity 133

the payroll information when the employee’s information document isopened. If the Virtual Field activity were not running, or if the user did nothave privileges to the DB2 data, the user would still see all of theinformation about the employee, but the payroll fields would be blank.However, if you had selected “Leave all real-time fields in documents” inthe Data Storage section of the General Options, the data would retain thelast refresh value before the Virtual Fields activity had stopped running.See “General Options” in this chapter for more information.

Virtual Fields and Public Key EncryptionIf any virtual fields have been enabled for encryption, and a PublicEncryption Key is provided in the document properties security tab, anyand all encryption enabled fields will be encrypted as with non-virtualfields. The corresponding data in the external system table will be nulled.The encrypted data will only be visible to Notes users with the appropriateencryption key. External system table columns which are mapped toencryption enabled virtual Notes fields should not have constraintspreventing NULL values or uniqueness constraints. Any encrypted virtualfield data will be stored within the key (stub) document.

Usage Requirements, Performance, and Mapping in Virtual FieldsActivities

There are three usage requirements to keep in mind:

• Indexing

• Key Field Datatypes

• HTTP Server

The indexing requirement is necessary for proper Virtual Fields activityoperation, as well as key field datatypes the HTTP server.

IndexingFor Virtual Fields, the following fields should be indexed:

• Mapped key fields

• All Sybase data tables


Key Field DatatypesAny field used for a key field in a Virtual Fields activity must be usable as akey field in the external system data source.

For each of the data sources listed below, the specified data types cannot beused as key fields in Virtual Fields activity.

• Oracle — LONG and LONG RAW types cannot be used as keys.

• DB2 — BLOB, CLOB, and DBCLOB types cannot be used as keys.

• Sybase — TEXT and IMAGE types cannot be used as keys.

• ODBC — Varies by specific external system; refer to the databasedocumentation.

• Notes — RICH TEXT fields cannot be used as keys.

Note Refer to the data source documentation for more information aboutthe use of data types as key fields.

HTTP ServerWhen using the HTTP server to access documents, do not use the VirtualFields update event option “Conflict Detection” because it relies on the useof hidden fields and the HTTP server does not save context information.

Performance in Virtual FieldsTo maximize performance in Virtual Fields activities, when the externalconnection is an SQL database, make sure an SQL index exists on the keyfields. For example, if the key fields for a Virtual Fields activity monitoringtable “MyTable” are “FirstName” and “LastName,” create an index in theSQL database as follows:

CREATE UNIQUE INDEX IndexName on MyTable (FirstName, LastName)

When the Virtual Fields activity is enabled, LEI opens the connection whenthe first event for that activity is processed. LEI closes the connection assoon as possible after the activity has been scheduled to stop. By default, asingle persistent connection is shared by all users of the Notes database. It ispossible to set the maximum number of concurrent, opened connections toincrease performance. See the Max. Concurrent Connections options in theVirtual Fields Options section.

Mapping and Unmapped ColumnsIn general, if there are unmapped columns in the Virtual Fields table, whichdo not accept NULLs, you will get a NULL assignment error when creatinga new record. The exact wording of this error depends on the connector youare using. This situation is particularly noticeable when you use a VirtualDocuments table as a “key document” for a Virtual Fields activity.


Creating a Virtual Fields Activity Using the User AssistantYou can optionally enable the User Assistant to prompt you the through thecreation of a new Virtual Fields Activity. You can toggle the User Assistanton and off using the Help option in the Navigator panel of theAdministrator.

This section describes how to create a Virtual Fields Activity using the UserAssistant. For options not described in these steps, see the chapters entitled“LEI Administrator” and “Introduction to LEI Activities.”

Step 1: Open the Activity DocumentIn either the Activity View or the Favorites View (or a Folder View), clickthe Add Activity icon in the Action bar. A message box opens that explainsthe steps the User Assistant will guide you through.


Note If you have not made any selections while the User Assistant is on,clicking the Cancel button on this message box closes the activity form andreturns you to the LEI Administrator. Once you have made one or moreselections while you are in the User Assistant, clicking Cancel causes theAssistant to shut down, but the activity document stays open, in Edit mode,displaying the choices you have made up to that point. You can thenmanually complete the activity document or abandon it.

Any choices you make while using the Assistant can be changed later byopening the activity document in Edit mode.

Step 2: Select the Domino DatabaseA list of Domino databases appears (see illustration below). Select theDomino database that contains the Notes form you want to monitor.

Note When the list is large, you can scroll down the list to find the dominoapplication (nsf) you want to select. However, if the list is too large to becompletely accommodated by scrolling, an overflow message appears at thebottom of the list (<overflow…>) and a box appears under the list, whichyou use to type in the exact name of the table you want to use. For moreinformation on browsing and browsing requirements, see “Browsing” in thechapter entitled “LEI Administrator.”


Note Immediate or “real-time” monitoring uses the Notes replication ID ofthe application database. A Virtual Fields activity does not distinguishbetween the databases that share the same replication ID. Databases havethe same replication ID when they are replicas of each other and when onedatabase is created using the operating system to copy an existing database.

Step 3: Select the Notes Form to MonitorA list of forms within the selected database appears. These are the formsyou will use to display external system data. Select a single form that youwant to monitor from the list shown.

Note Use the “Form Override” check box in the “General Options” sectionof the Virtual Fields Activity document to indicate that the Virtual FieldsActivity should monitor all forms within the database, regardless of theform it uses. This option is only applicable to Virtual Fields Activitydocuments. See the section on “Virtual Fields Activity Options” later in thischapter.


Step 4: Select the Lotus Connection for the Data SourceSelect the Connection for external data source you want to monitor fromthose available in the Select Connection dialog box, shown below.

Note When the list of tables is large, you can scroll down the list to findthe table you want to select. However, if the list of tables is too large to becompletely accommodated by scrolling, an overflow message appears at thebottom of the list (<overflow…>) and a box appears under the list, whichyou use to type in the exact name of the table you want to use. For moreinformation on browsing and browsing requirements, see “Browsing” in thechapter entitled “LEI Administrator.”


When you have selected a connection and there is more than one table inthe external database, another database opens asking you to select a table inthe external database. See the illustration below.


Step 5: Map Key and Data Field(s)After specifying the external data source and providing any requiredconnectivity information, such as user name and password, the Data FieldMapping dialog box appears. You must map key fields and data field(s)between the Domino application and the external data source. Theillustration below shows the interface for mapping key fields and datafields in a Virtual Fields activity.

Note If there are unmapped columns which do not accept NULLs, youwill get a NULL assignment error when creating a new record. SeeMapping and Unmapped Columns in “Usage Requirements, Performance,and Mapping in Virtual Fields Activities” in this chapter.

Note When you create an activity using an OLE DB connection, the keyfield should not be a TEXT, NTEXT or IMAGE datatype. These datatypescannot be used in an ORDER BY clause or in the WHERE, HAVING, or ONclause, except with the LIKE or IS NULL predicates.

Using the UNID as Key FieldLEI provides an option to use the Notes universal ID that is createdautomatically by Notes for each document when a document is created.This makes it unnecessary for you to include an extra field in your Notesfront end solely as a key field.


Step 6: Select Events to MonitorAfter mapping key and data field(s), the Virtual Fields Activity EventSelection dialog box appears. The last required step is to select the event(s)(create, open, update, delete) that you want to monitor. You see thisinterface only when you are creating or editing a Virtual Fields activitydocument.

Note You must select one or more events to monitor. You can select anycombination of events. You must select both Open and Update if you wantto monitor Update events. You will receive an error message if you justchoose Update.

Note The events that you are monitoring are on the Notes Form youspecified in this activity document, however, when you update, you updateto the external system. The user name is used to connect to the externalsystem must have read and write permission for that external system. If auser has only read rights, that user can open a document, but cannot updatethat document and save changes to the external system.


Step 7: Name the Activity DocumentWhen prompted, enter a unique activity name and click OK.

After you name the activity and click OK, the following informationalmessage box appears outlining your options.

Click OK and the Virtual Fields Activity document appears, showing yourselections. The numbers in the document correspond to the major steps theAssistant uses to create the Virtual Fields activity.


Step 8: Enable SubformsYou can select this option to allow the use of subforms that are controlledby a formula. Subforms that are not controlled by a formula are included bydefault. If you select this option, a dialog box opens that lets you select froma list of computed subforms. Include only subforms controlled by aformula.


Step 9: Select OptionsAt this point, you can select the specific options that you want for thisVirtual Fields activity. See “Virtual Fields — Options,” in this chapter for afull description.


Step 10: Select Scheduling OptionsChoose how to control scheduling of the Virtual Fields activity. The optionsare Manual, AutoStart, and Custom. See the “Scheduling” section in thechapter entitled “Introduction to LEI Activities” for more information.

Step 11: Save, Initialize Keys, and Close the DocumentYou must initialize keys once and only once.

Choose File - Save to save this Virtual Fields activity definition. This alsocauses the Initialize Keys button to appear.

Click the Initialize Keys button. You can now close the Virtual FieldsActivity document.

Choose File - Close to close the Virtual Fields Activity document and returnto the LEI Administrator.

Note For more information about Initializing keys, see “Initialize Keys inVirtual Fields” in this chapter.

Note If you have already created key documents, do not initialize keysagain.

Tip If you create a Virtual Fields Activity such that output parameters arebeing used and the field(s) to receive the data contain Hide When formulassuch as the following, you must manually refresh the form to see the HideWhen field value:

For field FIELD_FOO:

Hide When FIELD_FOO=""

After you save your document, the Hide When field value will remainhidden until you refresh the form.

However, if you add the following code to your form design Postsaveevent, using Domino Designer, the Hide When field value will bevisible immediately after you save your document, with no manualrefresh required.

Sub Postsave(Source As Notesuidocument)

Dim workspace As New NotesUIWorkspace

Dim uidoc As NotesUIDocument

Set uidoc = workspace.CurrentDocument

Call uidoc.Refresh

End Sub


Step 12: Process the Virtual Fields ActivityYou can process the activity using the Start and Stop buttons in the Actionbar of the Activities view or the Favorites (Folders) view.

Note When you select “Auto Start” in the Scheduling section of theactivity document, the Virtual Fields activity is established each time thatthe server starts. See the Scheduling section for more information.

Click the Virtual Fields Activity to select it and then click the Start button tobegin processing it.

Note To stop a Virtual Fields Activity, select the Virtual Fields activity andclick the Stop button.

Creating a Virtual Fields Activity without the User AssistantYou can optionally enable the User Assistant to prompt you the through thecreation of a new Virtual Fields Activity. You can toggle the User Assistanton and off using the Help option in the Navigator panel of theAdministrator. If you disable the User Assistant, a blank activity documentis displayed, which you can fill in to define the activity.

This section describes how to create a Virtual Fields Activity without usingthe User Assistant. For options not described in these steps, see the chaptersentitled “LEI Administrator” and “Introduction to LEI Activities.”

Step 1: Open the Activity DocumentClick the Add Activity icon. The Virtual Fields Activity Document appears.

Step 2: Enter a Name for the ActivityEnter a unique name for the activity in the Name field at the top of thedocument.

Step 3: Select the Domino Application and the Form to MonitorClick the down-arrow icon in the “Domino Application” section. A list ofdatabases appears. Select the database that contains the Domino applicationthat you want to monitor. You are also prompted for a form name.

Note If the list is large, you can scroll down the list to find the Dominoapplication (nsf) you want to select. However, if the list is too large to becompletely accommodated by scrolling, an overflow message appears at thebottom of the list (<overflow…>) and a box appears under the list, whichyou use to type in the exact name of the table you want to use. For moreinformation on browsing and browsing requirements, see “Browsing” in thechapter entitled “LEI Administrator.”


Note Immediate or “real-time” monitoring uses the Notes replication ID ofthe application database. A Virtual Fields activity does not distinguishbetween the databases that share the same replication ID. Databases havethe same replication ID when they are replicas of each other and when onedatabase is created using the operating system to copy an existing database.

Step 4: Select the Lotus Connection for the Data SourceClick the down-arrow icon in the External System section to select fromexisting Lotus Connection documents.


Step 5: Enable SubformsSelect this option to allow subforms controlled by a formula to be used.Subforms that are not controlled by a formula are included by default. Ifyou select this option, a dialog box opens that lets you select from a list ofcomputed subforms. Include only subforms controlled by a formula.


Step 6: Mapping Key and Data FieldsAfter specifying the external data source and providing any requiredconnectivity information, such as User Name and Password, the Data FieldMapping dialog box appears. You are required to map key fields and datafield(s) between the Domino application and the external data source.

Click the down-arrow icon in the “Mapping” section. The field mappingdialog box appears. Use this dialog box to map the key and data fieldsbetween the Domino application and the external data source.

The illustration below shows the interface for mapping key fields and datafields in a Virtual Fields activity.

Note If there are unmapped columns which do not accept NULLs, youwill get a NULL assignment error when creating a new record. SeeMapping and Unmapped Columns in “Usage Requirements, Performance,and Mapping in Virtual Fields Activities” in this chapter.

Note When you create an activity using an OLE DB connection, the keyfield should not be a TEXT, NTEXT or IMAGE datatype. These datatypescannot be used in an ORDER BY clause or in the WHERE, HAVING, or ONclause, except with the LIKE or IS NULL predicates.


Using the UNID as Key FieldLEI provides an option to use the Notes Universal ID that is createdautomatically by Notes for each document when a document is created.This makes it unnecessary for you to include an extra field in your Notesfront end solely as a key field.

Step 7: Select Event(s) to MonitorIf you are filling out a Virtual Fields form, you must select one or moreevents to monitor. Click the down-arrow icon in the Events section. Adialog box appears. Select the document events that you want to monitor.You can select any combination of events.

Note You must select both Open and Update if you want to monitorUpdate events. You will receive an error message if you just choose Update.

Step 8: Select Options and Event OptionsSelect the options and the event options you want in the “Options” and“Event Options” tabs in the document. See the section “Virtual FieldsActivity Options and Event Options” later in this chapter for moreinformation.

Step 9: Select Scheduling OptionsSelect how you want to control the scheduling of the Virtual Fields activity.The options are Manual, AutoStart, and Custom. See the “Scheduling”section in the chapter entitled “Introduction to LEI Activities” for moreinformation.

Step 10: Save, Initialize Keys, and Close the DocumentYou must initialize keys once and only once.

Choose File - Save to save this Virtual Fields activity definition. This alsocauses the Initialize Keys button to appear.

Click the Initialize Keys button. You can now close the Virtual FieldsActivity document.

Choose File - Close to close the Virtual Fields Activity document and returnto the LEI Administrator.

Note If you have already created key documents, do not initialize keysagain. For more information about Initializing keys, see “Initialize Keys inVirtual Fields” in this chapter.


Tip If you create a Virtual Fields Activity such that output parameters arebeing used and the field(s) to receive the data contain Hide When formulassuch as the following, you must manually refresh the form to see the HideWhen field value:

For field FIELD_FOO:

Hide When FIELD_FOO=""

After you save your document, the Hide When field value will remainhidden until you refresh the form.

However, if you add the following code to your form design Postsaveevent, using Domino Designer, the Hide When field value will bevisible immediately after you save your document, with no manualrefresh required.

Sub Postsave(Source As Notesuidocument)


Dim uidoc As NotesUIDocument

Set uidoc = workspace.CurrentDocument

Call uidoc.Refresh

End Sub

Step 11: Process the Virtual Fields ActivityYou can process the activity using the Start and Stop buttons in the Actionbar of the Activities View or the Favorites (Folders) View. (When you select“Auto Start” in the Scheduling section of the activity document, the VirtualFields activity is established each time that the server starts. See theScheduling section for more information.)

Click the Virtual Fields activity to select it and then click the Start button tobegin processing it.

Note To stop a Virtual Fields activity, select the Virtual Fields activity andclick the Stop button.


Virtual Fields Activity Document OptionsOnce you have specified the Domino application, the connection, and datamapping, there are several options to consider for setting up a VirtualFields activity.

The options are broken down into two major areas: Options and EventOptions

The Options tab is broken down into several areas or functions.

• General Options

• Multi-value Data

• Integrated Credentials

• Virtual Attachments

The Event Options tab is broken down into an optional set of areas.

• Create

• Open

• Update

• Delete

See the chapter entitled “Introduction to LEI Activities” for a description ofthe following sections that are common to all Activity documents:

• Activity Name

• Scheduling

• Category

• Comments

Note A Virtual Fields activity requires that you initialize keys or that “keydocuments” be created in some way. Initializing keys creates keydocuments based on the key field(s) in the LEI activity document. These keydocuments serve as data containers after the activity is enabled. Initializekeys only once. See “Initializing Keys in Virtual Fields Activities” in thischapter for more information.

Note If after upgrading DECS, or upgrading from DECS to LEI, youdiscover you are unable to get data when you are running Virtual Fieldsactivities, you may have to open each Virtual Fields activity document andensure that the Domino Server chosen in the activity document is correct.


General Options in Virtual FieldsThe General Options section of the Virtual Fields activity document,illustrated below, presents options that can be applied to an activityregardless of the type of Event the Virtual Fields activity monitors. Each ofthe General Options is described after the illustration.

continued

If you use more than one Virtual Fields activity for a singleNotes form, you can specify the order in which thedocument’s events are intercepted.

The monitor order also enables you to use multiple activitiesthat connect to different tables and use values found by thefirst Virtual Fields activity (monitor order 1) as keys forsubsequent Activities (monitor order 2, 3, etc.).

Note Activities with monitor orders of 2, 3, 4, and so on,must monitor an Open event. They may monitor otherevents too, but one of the events must be an Open event.Depending on the nature of the activity, the activity withmonitor order 1 may also be required to monitor an Openevent.

Monitor Order

DescriptionGeneral Options


continued

The default is to monitor only documents using the formspecified in the Domino Application section.

Selecting this option causes the Virtual Fields activity toprocess the selected events for all the documents in theNotes database that have the same key(s) as the originalmetadata, regardless of the form.

Form Override

This option sets the maximum number of connections to theexternal database that can be open to service concurrent userrequests simultaneously. LEI opens one connection to theexternal data source when the first Domino Applicationevent occurs. If two or more events occur simultaneously,additional connections are made, up to the maximumnumber of connections specified by this option.

When the maximum number of connections is reached,subsequent events are queued and occur when eachpreceding event is serviced. Each connection lasts only aslong as necessary to read from or write data to the externaldata source. While the connection is persistent, the timerequired to service each event is minimal and depends onthe amount of data being read or written. The maximumnumber of connections, therefore, does not need to be thatgreat in order to service multiple events. Lotus recommendsthat you set the maximum connections to 2 or 3, and if usersexperience significant delays, you can increase this number.

Max. Connections



continued

wwww Prevent data loss — Enable this option to have LEI writean error to the log for any data that is lost as a result ofthe transfer and terminate the transfer.

wwww Allow precision loss — Enable this option to have LEI notreport loss of numerical or datetime precision as a resultof the transfer. This allows some loss of precision withoutstopping the transfer. This option is the default.

wwww Allow precision loss & truncation of text — Enable thisoption to have LEI allow precision loss and to truncatetext data when necessary to conform to field lengths inthe external database. Note that key fields are nottruncated.

Data Integrity

An optional Notes formula defining the documents that theVirtual Fields activity will monitor. Use this option to causethe Virtual Fields activity to process only documents thatsatisfy the specified formula.

Note When you set up a Filter Formula, the selected fieldmust also be defined in “Saved Fields” under the DataStorage option (see below).

Note If you use Virtual Documents as a source for “keydocuments” in a Virtual Fields activity and you do not mapthe field(s) that you entered in the Filter Formula option inthe Virtual Fields Activity, you must select the “Leaveselected real-time fields in documents” option in the DataStorage field of the Virtual Fields Activity. If you do not dothis and a record that meets the filter formula is updated, itwill be removed from the Notes view because the filter fieldon the Virtual Document side is updated to NULL.Therefore, these fields must remain in the Virtual FieldsActivity. However, if the filter field is mapped as a key fieldin the Virtual Fields activity, you do not have to keep theselected fields in the Virtual Fields Activity. Keep in mindthat any additional fields mapped on the Virtual Documentsside will be displayed by the Virtual Fields activityregardless of whether the filter formula was met.

If a document is created that does not match the filtercriteria, it is not inserted into the external table (hence, it isnot “processed”), instead, it is saved locally in the .nsfregardless of the “Data Storage” setting.

Filter Formula



continued

Select the option you want to use to convert the Notesnew-line delimiter to a new-line delimiter in another system.

New Line Delimiterfor Connection

This option affects any trailing spaces that exist in the Textfields of the external data.

Text trimming only occurs when the fields are read from theexternal source.

wwww Trim spaces on all non key fields — Select this setting totrim trailing spaces only from data fields, not from thekey fields. (Default)

wwww Do not trim spaces on any fields — Select this option toleave trailing spaces in all fields.

Trailing spaces may be required to ensure matching of fieldsbetween Notes and the external data.

Note When data is put into external system fields of fixedlength and then retrieved, the connection with the externalsystem may be lost because the external system has paddedthe data with spaces to fit the fixed length of the field. If thisoccurs, use either a variable length field (VARCHAR) in theexternal system database, or enable the “Trim spaces on allnon key fields” option. You may encounter this situationwhen using data of type CHAR as a key field for Oracle 7 or8 external data sources. When you use a CHAR data type asa key field, use the default setting, “Trim spaces on non-keyfields.”

Note When using a Virtual Fields Activity that monitorsthe Create Event, key fields of type character (fixed length)are only effected by the activity’s trim options when keys arefirst initialized. While the activity is running, newly createdcharacter (fixed) key fields will remain exactly as they areentered when creating the new record in Notes.

Trim Trailing Spaces



Click the down arrow to open a list of Notes data fields fromwhich you can select the data field you want. If you do notselect any fields, it is equivalent to enabling the "Remove allreal-time fields from documents" option.

Note If you use the Filter Formula option, the selected fieldmust also be defined here in Saved Fields.

Saved Fields

wwww Remove all real-time fields from documents — Enablethis option if you want to remove all the data fieldsmapped in the Activity from the Notes document beforeit is saved to disk. This is the default.

wwww Leave all real-time fields in documents — Enable thisoption if you want to leave all the data fields in the Notesdocument, rather than removing them after updating theexternal source (see above). This option only takes effectwhen creating or updating a document when the activityis active.

wwww Leave selected real-time fields in documents — Enablethis option if you want to leave selected data fields in theNotes document. You may want to select this option inorder to enable views of the forms.

Data Storage


Initialize Keys in Virtual FieldsWhen you are working in a Virtual Fields activity document, there is abutton labeled “Initialize Keys” in the Action bar. When you click thisbutton LEI populates the currently selected Virtual Fields activity key fieldswith data from the external data source for that connection. This commandshould be used only once after creating a Virtual Fields activity. Initializingkeys again creates duplicates of existing documents.

If you have specified “Leave selected real-time fields in documents” or“Leave all real-time fields in documents,” the associated fields aretransferred to the Domino Application.

Note When using Initialize Keys with a Virtual Fields activity that has aFilter Formula, you are asked if you want to use a conditional clause torestrict the number of external records imported into Notes. If you chooseYes, you are prompted to enter the external conditional clause. Theconditional clause must be in the external system’s syntax for a keyedselection clause. For SQL based systems, the conditional clause is that partof a WHERE clause following the word “WHERE.” For example, if thecomplete statement were: SELECT * from Table WHERE Number > 1, youwould only enter Number > 1 as the key initialization condition.


Note In a Create event, character (fixed) key fields are unaffected by trimoptions they are also unaffected by how they are stored in the external datasource. These fields remain exactly as they were entered when creating therecord in Notes.

Caution When you create an activity using an OLE DB connection, the keyfield should not be a TEXT, NTEXT or IMAGE datatype. These datatypescannot be used in an ORDER BY clause or in the WHERE, HAVING, or ONclause, except with the LIKE or IS NULL predicates.

Multi-value Data in Virtual FieldsTo enable a LEI activity to work with multi-value data, check theMulti-value Data check box under the Options section of the activitydocument. This expands the section displaying additional selections. TheMulti-value Data options allow you to consider non-key fields asmulti-value fields. Once selected, there are more options for sorting andordering for you to choose from. Each Multi-value Data option is describedafter the illustration.


continued

Sorting key fields that define the order of the data within acollapsed record. The individual values within themulti-value data field are sorted according to the “Textorder” and the “Direction” options.

All remaining fields will have their multi-value dataappropriately sequenced to preserve their order with thoseof the sorting field or fields.

Sorting fields

Sort multi-value data — Enable this option to have theVirtual Fields activity sort data within the non-key fields.

When enabled, the values within the multi-value data fieldswill be sorted according to the sequence of the indicated“Sorting fields” and their relationships based on the type ofsorting (text, binary and ascending, or descending).

Also, when you enable this option, the Text Order, Direction,and Character Set fields become available.

Sorting

This is an additional key field (for one or more fields) thatdefines the unique key within a collapsed record. If youchoose more than one field, you can order them in any wayyou would like.

For example, if four orders by single customers are collapsedinto one document with the customer number as the key,and one order is changed, then the order number is requiredto ensure that the correct record is updated. In this example,the order number is the subkey and provides a uniqueidentification across the individual external records for thiscustomer when it is expanded back to the external datasource.

Subkey Fields

Use multi-value data fields — Enable this option to have theVirtual Fields activity consider non-key fields to bemulti-values.

Multi-value Data allows a single document in a Notesdatabase to relate to multiple records in the connection.When enabled, the Open event will read all records of theexternal system which match the key data field(s) andcombine the multiple fields data into Notes multidata fields.The Create, Update, and Delete events reverse the operation.

Note Multi-value data cannot be further controlled withconditional keys such as “Not Equal To” and “Less Than orEqual To”.

Multi-value Data

DescriptionMulti-value DataOptions


Force data into the selected character set for the purpose ofsorting. By default the underlying Connection’s character setis used. To provide a character set, use the correspondingsuffix. For example, for LCSTREAMFMT_IBMCP932, use“CP932.” See an appendix in the Lotus Connector LotusScriptExtensions Guide for a list of character sets.

Character set

wwww Ascending — Sorting is done alphabetically from A to Z.Earlier dates are placed before more recent ones; smallernumbers are placed before larger ones.

wwww Descending — Sorting is done alphabetically from Z to A.Recent dates are placed before earlier ones; largernumbers are placed before smaller ones.

Direction

wwww Binary — Sort based on the binary order of the charactercodes. Recommended.

wwww Case Sensitivity — Lower case is sorted before uppercase.

wwww Case Insensitivity — Case is ignored in the sortingprocess.

Text order

DescriptionMulti-value DataOptions

Multi-value functionality allows activities to group multiple records with acommon key value into a single Notes document. By using multi-valuefields, these records can appear, for example, as table data. All records withthe same grouping key field value(s) are combined (collapsed) until adifferent key is encountered. For example, to capture this information, youcould use Designer to create a two-row table on a Notes form and addingmulti-value enabled fields for multi-values, with separator options set to“new line.”

In all LEI activities, a key must be defined as one or more fields, forexample, “JOB” might be defined as the key field. In this case, the LEIactivity document would have a “Key” value field that is not a unique field.

SubkeysAn important option that allows changes to be written back to a data source(external system) is the “Subkey fields” option. This option makes itpossible for you to select a unique key to identify this individual record inthe external system data source.

For example, if six employees are combined (“collapsed”) into onedocument with the job title as the key, and data regarding one employee ischanged, then the employee number is required to ensure that the correctrecord is updated. In this example, the employee number is the sub key andprovides a unique identification across the individual external records forthis employee when it is expanded back to the external data source.


Also note that there are numerous sorting options as well. These optionsallow sorting on the data contained in the combined (“collapsed”) records.

Note You should use extreme caution when you update an existingsubkey. You should not, under any circumstances, update it to an existingsubkey. If you have a unique constraint on the subkey column and youmodify a subkey to a value that does not yet exist in the current record’sprimary key, you will get an insert error. If you do not have a uniqueconstraint, you will not get an error and the update will proceed normally.If, however, you update the subkey to another that already exists for thesame primary key, you may loose data even if you have a unique constrainton that column.

Integrated Credentials in Virtual FieldsUser credentials for the external system are automatically looked up whenthe Integrated Credentials options is selected. The credentials are used toconnect to the external system. This increases Domino security byintegrating it with the security already in place for the external system.

Note The integrated credentials database is described in the Introductionto Activities chapter of this document. See the section entitled “IntegratedCredentials Database” for information about setting up and usingintegrated credentials.

Each of the Integrated Credentials Options is described in the tablefollowing the illustration.


When you select this option the form expands to includethe following options:

wwww Missing Credentials — In case of a credentials lookupfailure, either the operation can fail (this is the defaultaction) or default credentials in the activity can be used.

wwww Credentials DB Filepath — The name of the credentialsdatabase to be used for storing Notes user names andcorresponding external systems credentials. The path isspecified relative to the LEI directory (for exampleleidir).

Note You must have created this database using thetemplate leicred.ntf. See “Setting Up and Using IntegratedCredentials” in the Introduction to Activities chapter of thisdocument.

wwww Connection Cache Size — Maximum number of distinctcredentials active at one time.

Lookup Credentials

When you select this option the form expands to includethe following options:

wwww Missing Credentials — You can select the UseConnector Credentials option. If you select this option,then in case of a credentials lookup failure, defaultcredentials in the activity can be used. If you do notselect this option, the operation can fail (this is thedefault behavior).

wwww Credentials UserId field — The name of the field thatcontains the user ID to use to connect to the externalsystem.

wwww Credentials Password field — The name of the field thatcontains the password to use to connect to the externalsystem.

wwww Connection Cache Size — Maximum number of distinctcredentials active at one time.

Note If you use Virtual Documents as a source for “keydocuments” in a Virtual Fields activity, you must put thecredentials ID and password in the Virtual DocumentsActivity Document, putting them in the Virtual FieldsActivity Document has no effect in this case.

Obtain Credentialsfrom Data

Uses the user ID and password that is specified in theConnection Document you are using in this activity.

Use ConnectorCredentials

DescriptionIntegrated CredentialsOptions



Integrated Credentials and Server to Server ReplicationIn order to perform server to server replication in conjunction withintegrated credentials, you must add the server ID of the server beingreplicated with to the integrated credentials database. For example, if youwant to replicate a Virtual Documents or Virtual Fields-enabled databaseon Server A to Server B, you must add Server B’s server ID to the integratedcredentials database on Server A.


Virtual AttachmentsThe Virtual Attachments feature allows you to use Notes to addattachments to the external system database. File attachments will be storedin the external system rather than in your Domino application. Once added,they can be accessed through the virtual views.

Note Storing the file name and Notes ID makes identification and retrievalof the attachments easier but requires additional columns in the externalsystem table.

The list of required and optional Virtual Attachment columns is as follows:

RequiredEICONTENTS

OptionalEIFILENAME

OptionalEIUNID

RequiredEIFILESIZE

RequiredEIFILEID

RequiredEIDBID

Required or OptionalColumn Name


You do not need to include the EIUNID or EIFILENAME fields in theattachments table. They are not needed by LEI, but LEI maintains them ifthey are provided. These fields allow external database applications tomore easily recognize and access the data outside of LEI/Domino. EIUNIDis the noteid value that corresponds to the EIUNID field in the row of thedata/key table. EIFILENAME is the name of the attachment as specified inthe note. You can control this functionality using the Store Optional Fieldsoption on the Activity Document.

An important restriction is that the virtual attachments table must be in thesame external system and in the same database as the external system databeing accessed by the activity. The virtual attachments table cannot residein a different external system or database than the one being used by theVirtual Documents Activity. This is because the same ConnectionDocument is used to access the external system.

The Virtual Attachments feature allows you to add attachments to virtualdocuments as you would to a native Notes document. The exception is thatfile attachments are stored in the external system rather than in yourDomino application. The attachment data is stored in a binary field in anexternal system table that you create. Other columns in the external systemtable store key data, which enables the activity to locate a specificattachment. A single table can be used for multiple Virtual DocumentsActivities. The following considerations are helpful as you use this feature.

• You must select the Virtualize Attachments option when you useattachments in a Virtual Document. You cannot save an attachment in aVirtual Documents Activity unless it is virtualized. If you do not, yourattachments will not be saved.

• If the “fixup” utility is run on the Notes database while a monitoreddocument is open, you must either close and reopen document or savethe document to access any restored Virtual Attachments. Forinformation about “fixup” see the Domino server documentation.


Select this option to add the attachment filenameand its Notes ID to the attachment table. This optionis not required.

Note Storing the file name and Notes ID makesidentification and retrieval of the attachments easierbut requires additional columns in the externalsystem table.

Additional data

Specify a separate table for the contents of theattachments.

In addition to the contents of the attachments, thislocation also contains a locator key. Optionally, thefile name and Notes ID may be stored as anadditional data element, select “Additional data”for this option.

Note When you create a virtual attachment table inSybase, the column names must be in upper case.

Note See the section entitled “Creating a VirtualAttachments Table” for complete step-by-stepinstructions.

Attachment table

Virtualize Attachments — You must select thisoption to be able to store attachments with yourvirtual documents. Enabling this option requiresthat you create and specify an external system tableto contain the contents of the attachment.

Note You must specify an attachment table inorder to create a virtual attachments table.

Attachments

DescriptionVirtual Attachments Options

Indexing Fields for Increased PerformanceIf you are using Virtual Attachments, the Virtual Attachment Table shouldbe indexed on EIFILEID. In addition, the Virtual Attachment Table EIDBIDcolumn should be indexed if the table supports multiple databases. It isused by multiple Virtual Documents activities, some of which monitorforms from different Domino databases.

Fields and Data TypesThe following table describes the necessary fields and data types that arerequired for the attachment table at the external system as well as the fieldsthat are required on the Notes form.


OLE Object

IMAGEBLOB(1048576)

IMAGEBYTELONG RAWEICONTENTSrequired)

TEXT(255)

VARCHAR(255)

VARCHAR(255)

VARCHAR255)

VARCHAR(255)

VARCHAR2(255)

EIFILENAME(optional)

TEXT(32)

CHAR(32)

CHAR(32)

CHAR(32)

CHAR(32)

CHAR(32)orVARCHAR2(32)

EIUNID[d](optional)

NUMBERLONG NTEGER

INTINTEGERINT INT NUMBER(8)

EIFILESIZE [c] (required)

NUMBERINTEGER

INTINTEGERINTINTNUMBEREIFILEID**(required)

TEXT(16)

CHAR(32)

CHARACTER(16)

CHAR(16)

CHAR(16)

VARCHAR2(16)or CHAR(16)

EIDBID**(required)

Access 2000SQLServer

DB2 [b]Sybase [a]InformixOracle

External System Data Types Attachment TableFields

** Index these fields at the external system to increase performance.

a) In case sensitive RDBMS’s, such as Sybase, column names must be inupper case, for example, EIUNID.

b) DB2 — with up to a 1MB attachment.

c) EIFILESIZE column length may be adjusted, but it must remain aninteger (X,0).

d) EIUNID is a DWORD, or an unsigned 32-bit integer. According to theformula 2^n - 1, this gives a maximum EIUNID of 4,294,967,295 whichrequires 10 digits.

Specifying the Attachment Table and SchemasBy default, if a schema is not specified for the virtual attachment table, theuser making the connection is used by default. For example, if the user isTESTONE and the schema is DBSOURCE, the user will be taken as theschema, TESTONE.MY_TABLE. If the virtual attachment table is pickedfrom the selection dialog, the schema name is added as a prefix. However,if the user types the table name in by hand and there is a difference betweenthe schema and the connection user, he must type the schema name as aprefix, for example, DBSOURCE.MY_TABLE.


Any attachments that were not entered into the external system through theVirtual Attachment process will not be accessible through either VirtualFields or Virtual Documents. For example, if you added attachments to theexternal system database through another process, for example SQLcommands, you cannot access them through Virtual Fields or VirtualDocuments. You can create the table using SQL commands.

Creating a Virtual Attachments TableIn the Virtual Documents and Virtual Fields Activity Documents, you canconfigure the activity to use a relational table to store file attachments asbinary objects by creating a virtual attachments table.

1. Click the “Virtual Attachments” tab in the middle of the ActivityDocument.

2. Click the Attachments: Virtualize Attachments option.


3. In the Attachment table field, enter the name of the table that you wantto create.

4. Optionally specify that you wish to store optional fields.

5. Click the Create Virtual Attachments Table button.

6. The Create Attachment Table dialog appears, enabling you to select theoptions that will set an optimal size limit for some fields and createindexes as appropriate for others. Complete the form using thedescriptions presented below.

• Table Name — This field displays the table name that you entered inthe “Attachment table name” field of the Activity Document.

Note You must include the owner name in the first part of the TableName entry. For example, to create a table named EMPTRANSFERwith an owner name of DB2ADMIN, enterDB2ADMIN.EMPTRANSFER in the Table Name field on the CreateAttachment Table form.


• Use Connector Credentials — You need a relational database user IDwith privilege to create metadata. If the user ID in the ConnectionDocument does not have this privilege, uncheck this box and enter adifferent user ID and password.

7. When you have completed the form using the dialog box descriptionsabove, click OK in the upper right of the form to continue.

8. A message appears, indicating success.

Note If the table already exists, you will prompted whether tooverwrite it. If you answer Yes, the existing table and all the data in itare erased. Since most connection types don’t allow existing tables tohave fields added or field properties adjusted by an external program,changing existing attachment tables that were incorrectly created is notsupported.

For information about which fields will be indexed by the table creationtool, see the section in this chapter entitled “Virtual Attachments in VirtualDocuments Activities.”

Event Options Create, Open, Update, and DeleteThe monitored events are events that occur in the monitored Notes formthat you specified in this activity document. The Create, Open, Update, andDelete sections of the Virtual Fields activity document, provide manyoptions that depend on the type of Event the Virtual Fields activitymonitors. Each of the options is described in the tables on the followingpages.


You must choose which events you want the activity to monitor. Theoptions are displayed specific to the type of event or events you choose tomonitor. You must choose at least one event to monitor. The document isillustrated below (in this illustration all event options have been selected).

Create OptionsWhen monitoring Document Create Events, several options are availabledepending on the choices you make. A description of each of the optionsfollows the illustration.


continued

Enable Procedure Output — This option is available only if astored procedure has been specified in the “Stored Procedure”field. When this option is selected, it opens up the “StoredProcedure Output Mapping” section of the activity document,where you enter input and output field names.

This option enables the return of data from a stored procedure inthe external system to the Domino Application (that is, the Notesdocument). The activity’s key(s) and field(s) are supplied to thestored procedure as input parameters.

To see the arguments that will be passed to the stored procedure,type the stored procedure name in this field and then press F9.The fields that will be passed to the stored procedure aredisplayed next to the stored procedure name.

Note Currently, only the Lotus Connector for DB2 and theLotus Connector for SAP (available for purchase separately)support output parameters.

StoredProcedureOutput

This option executes a stored procedure in the external datasource to store data that has been entered into the Notesdocument. The field(s) are supplied to the stored procedure asinput parameters. Domino/LEI supports stored procedurebrowsing.

To specify the stored procedure and see the parameters that willbe passed to the stored procedure and their order, type the storedprocedure name in this field and then press F9. The fields thatwill be passed to the stored procedure are displayed next to thestored procedure name.

In a Virtual Fields activity this includes the specified key field(s).

Note See the “LEI and Data” appendix for error situations youmay encounter using Sybase or OLE DB stored procedures thatreturn a result set.

StoredProcedure

This option executes a Notes formula language statement beforethe document data is stored. You can use this option to modifyexisting fields or to compute values for additional fields. Forexample:

FIELD LASTNAME:=@if(LASTNAME =““;“NA“;LASTNAME);””

Note If you are connecting to an Oracle external system and youmust use a text field(s) of fixed length as a key field(s), use aformula filter to pad the specific field to the correct length. Seethe Lotus Connector for Oracle 7 or 8 information in LotusConnectors and Connectivity Guide for more information.

Pre-CreateFormula

DescriptionCreate Options


wwww Domino Application — Specify the fields in the DominoApplication (Notes document) that will receive the storedprocedure output.

wwww Lotus Connection — Specify the fields from the externalsystem that contain the stored procedure output. The firstfield from the external system maps to the first destinationfield, the second external system field to the seconddestination field, and so on.

Note These fields must not be specified in the Mapping sectionof the activity document.

StoredProcedureOutputMapping


Open OptionsWhen monitoring Document Open Events, several options are availabledepending on the choices you make. A description of each of the optionsfollows the illustration.

continued

This option executes a Notes formula immediately afterdata is retrieved from the external system. You can use thisoption to compute additional fields or modify existingfields. For example:

FIELD FIRSTNAME := @if(FIRSTNAME =“Al“;“Albert“;FIRSTNAME);””

Note You should not use Post-Open Formulas whenusing conflict detection.

Post-Open Formula

This option executes a Notes formula before the documentdata is retrieved from the external system. This optionprovides you with an opportunity to compute additionalfields or modify existing fields used as key information,thereby altering data selection.

Pre-open Formula(Virtual Fields only)

DescriptionOpen Options


These fields are visible only if “Stored Procedure Output”in either a Create or an Update event has been selected, seeeither Create or Update event for more information.

Stored ProcedureOutput Mapping

If no matching external record is found for a document onopen, you can choose what the action should be:

wwww Create Record — This option creates a new record in theexternal database.

wwww Generate Error — This option generates a Notes errormessage box.

wwww Ignores — This option ignores the fact that there are nomatching record and opens the document even thoughit contains no data.

Missing ExternalRecords(Virtual Fields only)

This option executes a stored procedure in the externaldata source to determine the data that will be retrieved intothe Notes document.

To see the arguments that will be passed to the storedprocedure, type the name of the stored procedure in thisfield or select the stored procedure from the drop down listand then press F9. Domino/LEI supports stored procedurebrowsing.

In Virtual Fields, the specified key fields are displayed nextto the stored procedure name.

For Lotus Connectors that support procedure outputparameters, the key fields (in Virtual Fields activities) arepassed as input/output parameters and the other fields arepassed as output parameters.

Note See the “LEI and Data” appendix for error situationsyou may encounter using Sybase or OLE DB storedprocedures that return a result set.

Stored Procedure



Update OptionsWhen monitoring Document Update Events, several options are availabledepending on the choices you make. A description of each of the optionsfollows the illustration.

continued

When a document is updated, this option executes a storedprocedure in the external data source to update the data relatedto the document. The field(s) are supplied to the storedprocedure as input parameters.

To specify the stored procedure and see the parameters that willbe passed to the stored procedure and their order, type the storedprocedure name in this field and then press F9. The fields thatwill be passed to the stored procedure are displayed next to thestored procedure name. Domino/LEI supports stored procedurebrowsing.

In a Virtual Fields activity this includes the specified key field(s).


StoredProcedure

When a Notes document is updated, this option executes a Notesformula statement before the data is saved in the externaldatabase.

Pre-UpdateFormula

DescriptionUpdate Options


continued

Only Update Changed Fields — This option causes the VirtualFields activity to not update fields in the external data sourceunless the corresponding fields in the Notes document have beenedited.

Use this option if you have triggers in the external system thatmonitor updates to individual columns of a table.

Field LevelUpdates

Check External Data for Changes — This option ensures that theexternal data has not changed since the Notes document wasopened. If it has changed, an update to the external data sourcewill fail.

If this option is enabled and if you make changes to data in aNotes document and then save the document, you must exit thedocument before making any more changes — even though youhave saved the document.

Note “Conflict Detection” is not supported when you use anHTTP server to access documents.

Note In a Virtual Fields activity, if you turn on “ConflictDetection” and you connect to a Sybase external system, theSybase external system table must be indexed.

ConflictDetection

Enable Procedure Output — This option is available only if astored procedure has been specified in the “Stored Procedure”field. When this option is selected, it opens up the “StoredProcedure Output Mapping” section of the activity document,where you enter input and output field names.

This option enables the return of data from a stored procedure inthe external system to the Domino application (the Notesdocument). The activity’s key(s) and field(s) are supplied to thestored procedure as input parameters.

To see the arguments that will be passed to the stored procedure,type the stored procedure name in this field and then press F9.The fields that will be passed to the stored procedure aredisplayed next to the stored procedure name.

Note Currently, only the Lotus Connector for DB2 and theLotus Connector for SAP (available for purchase separately)support output parameters.




wwww Domino Application — Specify the fields in the DominoApplication (Notes document) that will receive the storedprocedure output.

wwww Lotus Connection — Specify the fields from the externalsystem that contain the stored procedure output. The firstfield from the external system maps to the first destinationfield, the second external system field to the seconddestination field, and so on.

Note These fields must not be specified in the “Mapping”section of the activity document.


The following three settings are available for key field updates:

wwww Block: Do not allow updates to key fields in the Notesdocument or the external data source records.

wwww Delete/Insert: Updates to key fields will cause the originalrecord in the external data source to be deleted and a newrecord with the new key added.

wwww Ignore: Do not update the key fields in the external datasource. If a key field is edited, the change will be stored withthe Notes document but the key field(s) in the external datasource will not change.

Key FieldUpdates(Virtual Fieldsonly)


Delete OptionsWhen monitoring Document Deletion Events, several options are availabledepending on the choices you make. A description of each of the optionsfollows the illustration.


These fields are visible only if “Stored Procedure Output”in either a Create or an Update event has been selected, seeeither Create or Update event for more information.


When a document is deleted this option executes a storedprocedure in the external data source to remove the datarelated to the document.


In Virtual Fields, the specified key fields are also displayednext to the stored procedure name. In Virtual Fields, onlythe NOTEID field is displayed.

For Lotus Connectors that support procedure outputparameters, the key fields (in Virtual Fields activities) arepassed as input/output parameters and the other fields arepassed as output parameters.

Note See the “LEI and Data” appendix for error situationsyou may encounter using stored procedures that return aresult set with Sybase or OLE DB.

Stored Procedure

Notes formula language statement to execute on the Notesdocument immediately prior to the deletion in the externaldata source.

Here is an example that sends an E-mail containinginformation about a deleted document:

FIELD LASTNAME:=LASTNAME;

FIELD FIRSTNAME:=FIRSTNAME;

@MailSend(“John Q Public“;““;““;“Doc Deleted“;“Docdeleted from MyDatabase w/ Firstname/Lastnameof:“;FIRSTNAME:LASTNAME);””

Note It may be necessary to specify that activity data besaved in the Notes document; otherwise, the specifiedformula may access the field values after they’ve beendeleted. If this were the case for the example above,FIRSTNAME and LASTNAME would be empty. To specifythat activity data be saved, in the General Options sectionof the activity form go to “Data Storage,” choose one of theoptions “Leave all/selected realtime fields in document.”

Pre-Delete Formula

DescriptionDeletion Options


Running Virtual Agents Against Virtual FieldsChanges made to Virtual Fields documents by running a Virtual Agent willproduce updates in the specified documents immediately. However, if theVirtual Agent is updating values contained within a View column, thatview will not reflect the changes made to the documents, and pressing ShiftF9 will not refresh the view.

In order for Virtual Fields to be displayed within a view, you must haveselected “Leave all/selected Real Time fields in document” when buildingthe activity. This, in effect, makes native copies of the fields within thedocument. These fields will not be updated or reflect changes made in theexternal system until the Notes document is updated manually or by usinga formula or script.


Chapter 13 Virtual Documents Activity




• Virtual Agents

This chapter provides information about the Virtual Documents Activity.

Introduction to Virtual Documents ActivitiesVirtual Documents Activities monitor Notes forms. LEI connects theseforms to external data sources (such as DB2) using Lotus Connectors.

Once a system administrator has created a Virtual Documents Activity,Domino users can open, create, update or delete external data directly andtransparently through their Notes client. By extension, Web clients mayopen the same Notes form that the activity monitors by accessing a DominoRelease 6 server and obtain access to supported external source data.

For example, if the external database to be queried or updated from theNotes form is a DB2 database, Notes end-users may work with DB2 data asif it were in Notes. DB2 connectivity software is not required on the clientsystem, however, it must be installed on the Domino server machine.Network access to the external data source is handled by the Domino servermachine, which contains LEI connectivity software for the external datasource, such as DB2. You will be required to add certain fields to theexternal system to accomplish this functionality.

Comparing Virtual Documents and Virtual FieldsA Virtual Documents Activity makes it possible to have documents that arestored in the external system appear to reside in Domino. The functionalityprovided by a Virtual Documents Activity is similar to that provided by aVirtual Fields Activity. The important distinction between Virtual Fieldsand Virtual Documents Activities is that Virtual Documents do not requirethe presence of “key documents” (previously referred to as “stubdocuments”) that need to have the key fields initialized. Virtual Fields dorequire these documents and require key field initialization. Another

179

important distinction between Virtual Fields and Virtual Documents is thatVirtual Documents data fully participates in View operations.

A Virtual Documents Activity stores information that determine the note’sunique identity in the external system itself. Together, this informationprovides the unique keys to the external system records and are fullymanaged by LEI. Synchronization issues, which may arise in Virtual FieldsActivities between key documents (generated using the Initialize Keysoption) and the corresponding external system records, do not exist withVirtual Documents Activity because a Virtual Documents Activity does notgenerate or use key documents.

Like Virtual Fields Activities, the Connection Document for the selectedexternal system must be created before you create the Activity Document.You create a Virtual Documents Activity Document that specifies whichLotus Connector to use to access the external system and which Notesdatabase and form to monitor. Like all other LEI functionality, once aVirtual Documents Activity is defined it is controlled by the LEIAdministrator.

Also like Virtual Fields Activities, the fields in the form monitored by theVirtual Documents Activity are mapped to external system table columnswhen you create the activity. The mapping can be edited any time that theactivity is not running. The LEI Administrator provides browsingfunctionality to allow you to easily map an external system table andcolumns to the corresponding Notes database/form and fields.

Unlike Virtual Fields, you do not specify key fields because unique keyswill be generated and stored in the external system. For each VirtualDocuments Activity, only one form can be monitored. For each form, onlyone Virtual Documents Activity can monitor it.

Note All fields on the form must be mapped. Since none of the documentsresides in the .nsf file, all field data is retrieved from the external systemdatabase. Any fields that are not mapped to external database fields willnot be stored.

The use of Virtual Documents in combination with Virtual Fields isdescribed in the “Using Virtual Fields with Virtual Documents” appendix.

Advantages of Using Virtual Documents ActivitiesThere are several advantages to using Virtual Documents over VirtualFields Activities.

• No component of the actual Notes document is stored natively in theDomino application, however, all the data is available to a Notes userand is indistinguishable from data actually stored in Notes.


• You are not required to maintain key documents in Notes applications,making it more scalable and easier to maintain.

• Virtual Documents fully supports views and view refreshes. Bycontrast, Virtual Field data will not appear in a Lotus Notes viewsunless the user elects to leave selected non-key Virtual Fields monitoredfields in the key document, these could potentially contain stale dataeven after refreshing the view.

• Virtual Document Activities support background virtualization ofrecords added to the external system. This process automatically addsnew records that have been added to the external system to views. Italso virtualizes all records in the existing data table that have not beenvirtualized.

The following illustration shows the advantage of Virtual Documents overVirtual Fields. In a Virtual Fields Activity there are numerous “keydocuments” present. These often yield a large Notes database. However ina Virtual Documents Activity, there are no key documents. The VirtualDocuments Activity co-manages the Notes database along with Dominoand creates “virtual” documents as needed. When the Virtual DocumentActivity is not running, you cannot access any of these documents or theirassociated external data.

Chapter 13: Virtual Documents Activity 181

Using Virtual Fields and Virtual Documents ConcurrentlyYou can concurrently use Virtual Fields Activities with Virtual DocumentsActivities in the same Notes database. It is even possible to monitor thesame Notes Form with a Virtual Documents Activity and one or moreVirtual Fields Activities at the same time. In this scenario, the VirtualDocuments Activity first builds the Virtual Document from the externalsystem data, and then the Virtual Fields Activity uses a key(s) from theVirtual Document to further populate the document from potentiallyanother external system data source. This makes it possible to use some ofthe field level flexibility, and monitor order capability, of Virtual FieldsActivities but without the need for key documents.

See the appendix “Using Virtual Documents with Virtual Fields” for acomplete discussion of this topic.

Virtual Documents and Public Encryption KeysIf any fields in a Virtual Document have been enabled for encryption, and aPublic Encryption Key is provided in the document properties security tab,any and all encryption enabled fields will be encrypted as with non-virtualdocuments. The corresponding data in the external system table will benulled. The encrypted data will only be visible to Notes users with theappropriate encryption key. External system table columns which aremapped to encryption enabled Notes fields should not have constraintspreventing NULL values or uniqueness constraints.

Encrypting many fields may necessitate the size of the EINOTEPROPSbinary Virtual Document column to be increased beyond the typicalrecommended value of 10KB. This is particularly true if Rich Text fields orlarge text fields are encrypted. If Rich Text fields are encrypted, the size ofEINOTEPROPS should be increased by the same size as the binary datatypecolumn which is mapped to the rich text field. For example, if an encryptedrich text field “memo” is mapped to a corresponding external system tablebinary datatype column called “memdata” with a size of 5KB,EINOTEPROPS should be 15KB in size (the recommended 10KB size plus5KB to hold the encrypted data from the memo field). These represent“rules of thumb”, and depend on the number of encrypted fields, whetherthere are any encrypted rich text fields, the total number of fields and otherfactors. See the section entitled, “Required External System Fields forVirtual Documents Activities” for more information about EINOTEPROPS.


Virtual Documents and Monitored FormsWhen creating a Virtual Documents Activity, you must specify which Notesform the activity will be monitoring in your Domino database and specifythe mapping between the form fields and the external system tablecolumns. The connectivity information to the external system is defined in aseparate Connection Document, which must be created separately beforecreating a Virtual Documents Activity.

With the activity running, you can then create a new Notes document usingthe monitored form and save it; a new record will be created in the externalsystem table containing the data you entered along with the extrainformation needed by Notes to treat this record as if it were a “normal”Notes document. When you later open the document it will be displayedusing the correct Notes form. Any Notes database links, doc links,attachments, and so on, that you create remain intact in the VirtualDocuments. Views containing view selection formulas will correctly displayor not display your Virtual Documents, as required by the selectionformula.

Virtual Documents can be opened, updated, deleted, or created as long asthe Virtual Documents Activity is running. Updating or deleting VirtualDocuments will perform the corresponding action in the external systemtable. If you create a document with a different Notes form, or shut downthe Virtual Documents Activity, a document is still created but it will be anative Notes document and no corresponding record will be created in theexternal system table. Similarly, if you attempt to open a Virtual Documentbeing displayed in a Notes view but the Virtual Documents Activity is nolonger running, you will not be able to open that document. Refreshing theview while a Virtual Documents Activity is not running causes all of thenon-native document information to disappear from the view.


If another external system client (non-Notes) alters the external system table data, changes will not become immediately apparent in the Dominoapplication until the Notes view is refreshed. Use Shift + F9 to refresh aview if data is altered in this way. The same is true of newly created data. If another external system client creates records, the newly created recordsare automatically virtualized (if you enable the “Virtualize External SystemData” option in the General Options sections of the Activity Document) andwill appear in the view when it is refreshed. If records are deleted throughanother external system (non-Notes) client, they will be removed from the view when refreshed. However, it is recommended that deletions areperformed with the Notes client through the Virtual Documents Activity.This helps ensure the integrity of other Domino processes, such as replication,as it concerns Virtual Documents. For more information, see the sectionentitled “Special Consideration when Deleting Virtual Documents”.

Multiple Virtual Documents Activities can run against a single Dominoapplication (.nsf), each monitoring a separate Notes form. VirtualDocuments Activities can use separate connections and external systemtables, potentially on completely different external systems (for example,DB2 and Oracle). The Notes form information is preserved so the VirtualDocument data will always be displayed using the same form from which itwas created.

Note An external system table can only contain Virtual Documents datafor a single .nsf and form. Virtual Documents Activities monitoringdifferent .nsf files and forms must use different tables. This applies to bothdata tables and key tables.

Virtualizing Preexisting DataA special situation occurs when the external system table to be used with aVirtual Documents Activity contains preexisting data or when new rowsare added to the table from outside of Notes. A powerful feature of VirtualDocuments is the ability to virtualize this data “on the fly”, thus making itavailable to your Domino application. To enable this ability, select the“Virtualize External System Data” option in the General Options section ofthe Virtual Documents Activity Document. It is selected by default.

When the activity is started, any new rows in the external system will bevirtualized before the activity is available (before the activity startedmessage is printed to the log and/or console). If you are starting an activityagainst external system data with a large number of new rows (for example,virtualizing a large database for the first time), this process could takeseveral minutes or may take more than one hour.


After the activity is started, any new records added to the external systemwill be virtualized periodically, based on the Refresh Frequency valuespecified in the Activity Document.

Newly virtualized records are automatically assigned the Notes form thatthe Virtual Documents Activity is monitoring and will use that form whenthey are opened.

Understanding Virtualization ProcessingVirtualization occurs as a background task. Initial virtualization occurswhen the activity is started. Activity status is reported to the activity log.The log indicates when the virtualization is started, when it completed, andthe number of records that were successfully virtualized.

Although the log states that the virtualization process has started, it is notactually enabled until the initial virtualization process is complete.Attempting to access or create virtual documents before this initial cycle iscomplete will yield an error message.

Virtualization errors will appear in the activity log if there are problemsduring the background virtualization.

Required External System Metadata for Virtual Documents ActivitiesA Virtual Document Activity does not require key documents in the sameway that a Virtual Fields Activity does. However, it does require that therebe a table in the external system with four special columns that map toDomino-generated control fields. There are two ways to do this.

• Add the four control data columns (described below) to the externalsystem data table directly. This is the table that will be mapped to theNotes form in the Virtual Documents Activity.

• Create a separate table, called an External Key Table, at the externalsystem that contains only the four control data columns plus a foreignkey field(s) to map to the actual data table.

Note You can use the Table Creation Utility button to create thisseparate table (External Key Table) automatically. See “Using theCreate External Key Table Option” in this chapter for completeinformation. If you elect to use an external key table to store the Notescontrol fields, the key table must reside in the same database and havethe same user access rights as the data table.


If you select the second method, you specify the name of the External KeyTable in the Virtual Documents Activity form and the key(s) used to mapthe key table to the actual data table. These keys can be made up of acombination of fields. The advantage to this method is that you do not needto alter an existing data table.

In either method, the additional four control data columns areautomatically mapped to corresponding internal Notes fields when theVirtual Documents Activity is created. You do not need to map them in theMapping section of the Activity Document. They do not even appear whenyou enable manual mapping. There is nothing you have to do to ensuretheir being mapped other than be certain that the names and data types arecorrect.

The four additional Notes control data column names required are asfollows:

• EINOTEID

• EIUNID

• EIMODIFIED

• EINOTEPROPS

Theses column names must not be altered. Sybase users must name thesecolumns using all upper case characters.

For details regarding setting up an External Key Table, see the followingsection “Creating an External Key Table with Virtual DocumentsActivities.”

Note The external system column names, whether added to the existingdata table or created in an external key table, must match these namesexactly and must be of the appropriate data types. See the section belowentitled “Virtual Notes ID Data Type Correspondence for VariousDatabases” for the appropriate data type for a specific external system.

Note The information that LEI writes to the EINOTEPROPS field isderived from internal Domino fields. This information has the potential togrow over the life of the document. To minimize the chance that thisinformation will overflow the EINOTEPROPS field and to control howmuch space is required to store this information, see “Restrictions” in the“Creating an External Key Table with Virtual Documents Activities” sectionin this chapter.


Virtual Documents Required Column Data TypesFor each type of external system the table below shows the data type to usefor each of the required columns.

OLE object

IMAGE orbinary(255) [a]

BLOB(2GBorVARCHARFOR BIT DATA[a]

IMAGE or binary(255)[a]

BLOB (10K)[a, c]

RAW(2K)or LONGRAW(10K)[a, b, c]

EINOTEPROPS

DATETIMEDATETIMETIMESTAMPDATETIME DATEDATEEIMODIFIED***

TEXT(32)CHAR(32)CHAR(32)CHAR(32)CHAR(32)or VARCHAR2 (32)


EIUNID***

NUMBERINT(default tozero)

INTEGER(default to zero)

INT (default tozero)

NUMBER(default tozero)

NUMBER(default tozero)

EINOTEID***This field must notbe null


DB2Sybase (seeNote below)

Oracle 8Oracle 7

External System Data Types **Required Field

Note In case-sensitive RDBMS’s such as Sybase, column names must be inupper case.

** For all applications, it is strongly recommended that you limit thenumber of revision entries maintained for Virtual Documents. In thedatabase advanced properties tab, set the “Limit entries in $Revisionsfields” and “Limit entries in $UpdatedBy fields” to three or less.

*** It is recommended that the EINOTEID and EIMODIFIED columns beindexed to improve overall performance. Index EIUNID if you use VirtualDocuments Activities to support a Domino Web application.

[a] — Binary data type size is recommended value. Increase this value forvery large forms (for example, more than 100-150 fields) if you anticipate alarge number of file attachments or database/document links, or ifmaximum revision/update history is not set. When in doubt, or if updatesfail, select a larger value.


[b] — Because Oracle 7 limits a user to one long data type per table anddoes not support BLOBs, you will need to use RAW which has a maximumsize of 2KB. A LONG RAW can be used if no other long data types arebeing used in the table.

[c] — If made to work with LONG RAW, there must be no other LONGswithin either the data or the key table.

Considerations for EINOTEPROPSOf the four control columns required to support Virtual DocumentActivities, EINOTEID, EIUNID, and EIMODIFIED have a fixed size withspecific storage requirements. The EINOTEPROPS column has variablelength requirements and requires some special consideration. For mostapplications, a maximum size of 10KB is sufficient.

The EINOTEPROPS column is used for miscellaneous attributes of theVirtual Document which do not need to have separate columns dedicatedto them in the external system. Some of the information which is stored inthe EINOTEPROPS field has the potential to grow over time and couldeventually exceed the EINOTEPROPS field size limit. The size of theinformation written to the EINOTEPROPS field can be controlled in theNotes database properties box (for the .nsf that you have named in theActivity Document). Open the Advanced properties tab. If the options inthe Advanced tab are not visible, have your system administrator changethem. The Advanced tab contains options that allow you to limit theamount of data written to the EINOTEPROPS field. These options are“Limit entries in $UpdateBy Fields” and “Limit entries in $Revisionsfields.” Lotus Software recommends that you set them to 2 (64 bytes ofdata) or a maximum of 10 (640 bytes of data). The default value of 0 forthese settings means “no limit.”

If any of the Notes fields in the form are enabled for encryption usingpublic key encryption, that adds to the amount of data stored inEINOTEPROPS for each encrypted field in a given document. You mayneed to increase the maximum size for EINOTEPROPS if you areencrypting many fields. See the section entitled “Special ConsiderationsWhen Using Public Key Encrypted Fields” later in this chapter for moreinformation.


Considerations for EIMODIFIEDIf changes are made directly to an external system data table (outside ofDomino), the EIMODIFIED time stamp should be updated. Doing thisenables LEI to determine that the record has changed. This is important inenabling the following features:

• Conflict detection — If a user attempts to write a copy of the documentwhich they had been editing when the external system updateoccurred, they will be notified that a change has been made and beasked if they want to save a conflict document. If the external systemEIMODIFIED is not updated, the external system changes would beoverwritten. As with any conflict situation, you must evaluate how toresolve it.

• Replication — Changes to the table will not be replicated to replicas ofthe database unless the EIMODIFIED is updated.

• Indexing — Under some circumstances, indexes are incrementallyupdated to include added and changed documents. Views may notdisplay current information until a full index is rebuilt. You can rebuildan index by pressing the Shift F9 keys.

Using and Testing the Required External System FieldsBefore you test or use a Virtual Documents Activity, you should performthe following tasks:

1. Create a form to be monitored by the Virtual Documents Activity. Thisform must contain the fields that will be mapped to the external systemdata table columns.

2. Add the four required columns (EINOTEID, EIUNID, EIMODIFIED,and EINOTEPROPS) to the external system data created in step 1 orcreate an external key table.

If using an existing data table — If the data table already containsrecords, you may be prevented from adding these four columns. If thisoccurs, create a new table containing the same metadata, add the fourrequired columns, and copy the existing records to the new table.Modify the EINOTEID and set the value to zero. Use SQL if possible.

If creating an external key table — When possible, use the CreateExternal Key Table option on the Activity Document, which does notrequire that you alter the existing data table, and does allow you to“virtualize” your existing data into your specified Domino application.


3. Create the Virtual Documents Activity by clicking the Add Activity -Virtual Documents menu sequence from the LEI Administrator. If youchoose to create an external key table, the instructions are very specificand can be found in this document in the section entitled “Creating anExternal Key Table from the Virtual Documents Activity”.

4. Create a view in the Notes database based on the form being monitoredby the Virtual Documents Activity that can display the data fieldsmapped to the external data.

5. Start the Virtual Documents Activity by clicking either the Start buttonat the top of the Activity Document or by highlighting the activity namein the LEI Administrator’s Activity View and clicking the Start Activitybutton.

6. In the LEI Administrator’s Activity View, press the F9 button to ensurethat the activity has started without error.

Note The activity virtualizes all existing unvirtualized records whenyou start the activity and before the activity actually become available,with the following caveat. If you disable the Virtualize External SystemData option on the Activity Document, this does not occur.

7. The “Activity Started” message indicates that the activity is processing.Check the activity log to see whether the activity has completed. Ensurethat the Notes view you are using is designed to display data thatcorresponds to fields you have mapped to external system data andthat the view does not contain a selection formula that excludes theform that the Virtual Documents Activity is monitoring. Data is“virtualized” once at start up and again at specified intervals. Thisprocess occurs in the background whenever the Virtual DocumentsActivity is running.

Note Any new data rows that are added by a non-Notes process willbe deleted and automatically virtualized in the same manner. You mayneed to press the F9 button to refresh the view. Once the externalsystem data is virtualized, a message will appear in the activity log andthe activity will become accessible.

8. Perform the two tasks below to ensure that you have configured therequired tables correctly:

The processes of creating, opening, updating, and deleting of VirtualDocuments should behave just as in any other native Dominodocuments. For example, creating a new virtual document using theNotes client results in new rows being inserted into the external systemtable. Deleting a virtual document may remove the table record. If thereis no existing data, enter a record and perform one of these tasks.

Note See the section entitled, “Special Considerations When DeletingVirtual Documents” for related information.


Note Virtual Documents respect the security settings of the externalsystem data source. For example, if a user does not have sufficientprivileges to create a new row in the external system table being usedby the Virtual Documents Activity, he will be unable to save thedocument. The action will fail with an appropriate error.

a. To test the background virtualization manually, add a test row tothe external system using , for example, a SQL client. The test rowmust also use contain and entry for EINOTEID and be set to a zerovalue. This is most easily tested if the Refresh Frequency option onthe Activity Document is set to one minute. Alternatively, you canjust stop and restart the activity.

b. When the activity starts, it immediately begins to virtualize allunvirtualized external records. The new virtual document,corresponding to the new external records should then appear inthe view. Again, you may need to periodically press the F9 key torefresh the view. Once it appears in the view, open and update thedocument.

c. Shut down the activity. Refresh the Notes view. All the virtualdocuments should disappear from the view.

Note Indexing can improve performance. See the section entitled“Indexing to Increase Performance” for more information.

Indexing to Increase PerformanceIndexing is an important requirement for proper Virtual DocumentsActivity operation, as well as for proper operation of Virtual Attachmentswhen they are used with Virtual Documents Activities.

For Virtual Documents, it is strongly recommended that the followingexternal system table columns be indexed for maximum performance.These are some of the additional columns you need to add to the data table,or to an External Key Table:

• EINOTEID (always)

• EIMODIFIED (always)

• EIUNID (if Virtual Documents Activities are used to support a DominoWeb application)

• Additionally, if you are using the External Key Table, you should alsoindex the data key(s) (the foreign keys) used to map the External Keytable to the data table.

See the section entitled “Required External System Fields for VirtualDocuments Activities” for more information.


Note When using a Sybase database with Virtual Document Activities, thedata table must be indexed.

The following matrix shows the columns to index to increase performancein Virtual Documents and in Virtual Attachments:

Always when using external key tables.RForeign Key

When supporting Web applications throughDomino’s HTTP server.

OEIUNID

AlwaysREIMODIFIED

AlwaysREINOTEID

When to Use Required or OptionalColumn Name

Special Considerations When Using Public Key Encrypted FieldsIf any of the fields in a Virtual Document form have been enabled for PublicKey Encryption, and a field is subsequently encrypted in a given virtualdocument, the following behavior and considerations should be noted.

• The external data for the publicly encrypted field will be set to NULL inthe external table, and will only be visible in the Virtual Documentwhen opened by a user with appropriate privileges. At no time will thedata be visible in the external table. The table column which will bemapped to the public key encryption enabled field must be set to allowNULL values and duplicate values, otherwise saving a VirtualDocument with encrypted data will fail.

• The encrypted data is stored in the EINOTEPROPS column in theexternal table for the Virtual Document containing encrypted fields.Because of this, you may need to increase the size of EINOTEPROPSbeyond the recommended value for this binary column. Generally if theamount of encrypted data is relatively small and of a known quantitythis is not an issue. However, if the encrypted fields could potentiallyhold large arbitrary amounts of text, care should be taken to limit theamount of text in the field, or increase the size of EINOTEPROPSaccordingly. For example, a Manager’s Comments text field, as opposedto a employee salary Number field, could become very large if themanager is too verbose. To get a better idea of the amount of encrypteddata in a given document, examine the Document Properties Items tabto determine the amount of data encrypted in a typical document. Lookfor $SealData items and the Data Length of each, where each $SealDataitem represents an encrypted field in the document.


Special Considerations When Deleting Virtual DocumentsThere are two issues to consider when deleting Virtual Documents; deletionstubs and soft deletions.

Deletion StubsDomino employs a concept called “deletion stubs” when a document isdeleted. This means that even though the document data is deleted from theDomino database, a stub of the former document remains in order for otherDomino services to function correctly. For example, when replicating adatabase, the stub identifies the deleted document so that its replica is alsodeleted in the replica database. When using Virtual Documents, this“deletion stub” is represented in the external system database in one ofthree ways.

• If an external key table is used, the stub is effectively maintained in thekey table and the actual data row in the data table is deleted. The onlyspecial consideration is that the data key column(s), in the external keytable only, should be set to Allow Duplicate Values, even if thecorresponding key in the data table is unique.

• If you do not use an external key table because you have elected toappend the four Domino control columns (EINOTEID, EIUNID,EIMODIFIED, and EINOTEPROPS) directly to the data table, by defaultthe table row is not removed. When a Virtual Document is deleted, it isrecognized by Domino as a deleted document and will not be accessibleto any Notes user. However, interrogation of the external system tableusing a SQL client or other external system client will show that the rowis in fact not deleted. It remains intact with all the original data. Onlythe Domino control fields have been changed to designate it as adeletion stub, thus rendering it deleted from Domino’s perspective.

• If it is unacceptable to have the external system data still visiblethrough a non-Notes client, disable the Maintain Deletion Stubs optionin the Activity Document. However, this action prevents Dominodeletions from being seen in database replicas. It may also causeunexpected behavior if replicas of the deleted virtual documents aresubsequently updated.

Note If you use the Create External Key Table on the ActivityDocument, you should not disable the Maintain Deletion Stubs option.


Soft DeletionsDomino also supports the notion of soft deletes. If a Notes database has thisoption enabled, all deletes result in the documents being made invisibleexcept in a specially designed view, analogous to the familiar desktop trashbin. A soft-deleted document can be undeleted at any time. Soft-deleteddocuments can be set to expire after a certain time interval, when thespecified time interval has been reached, the documents are permanentlydeleted from the Notes database automatically.

Virtual Documents Activities completely supports Domino soft deletions. Asoft-deleted Virtual Document appears untouched if viewed in the externalsystem through a non-Notes client, but will behave exactly as soft-deleteddocuments in the Notes database. When the document is permanentlydeleted it will be deleted from the external system. See the section entitled,“Special Considerations When Deleting Virtual Documents” for moreinformation.

Creating a Virtual Documents Activity Using the User AssistantThis section describes how to create a Virtual Documents Activity using theUser Assistant. For options not described in these steps, see the chaptersentitled “LEI Administrator” and “Introduction to LEI Activities.”

Note You can optionally enable the User Assistant to prompt you thethrough the creation of a new Virtual Documents Activity. You can togglethe User Assistant on and off using the Help option in the Navigator panelof the Administrator.



If you have not made any selections while the User Assistant is on, clickingthe Cancel button on this message box closes the Activity Document andreturns you to the LEI Administrator. Once you have made one or moreselections while you are in the User Assistant, clicking Cancel causes theUser Assistant to shut down, but the Activity Document stays open, in editmode, displaying the choices you have made up to that point. You can thenmanually complete the Activity Document or abandon it.

Note Any choices you make while using the User Assistant can bechanged later by opening the Activity Document in edit mode.


Step 2: Select the Domino DatabaseA list of Domino databases appears (see illustration below). Select thedatabase that contains the Notes form you want to monitor.

Note The database selected must reside on the server where LEI isinstalled. If you wish to use LEI RealTime functionality in a database thatresides on a different Domino server, LEI must be installed on that server.

Note If the list is too large to be completely accommodated by scrolling, anoverflow message appears at the bottom of the list (<overflow…>) and abox appears under the list, which you use to type in the exact name of the.nsf file you want to use. For more information on browsing and browsingrequirements, see “Browsing” in the “LEI Administrator” chapter.

Note Real time monitoring uses the Notes replica ID of the applicationdatabase. A Virtual Documents Activity does not distinguish between thedatabases that share the same replica id. Databases have the same replica idwhen they are replicas of each other and when one database is createdusing the operating system to copy an existing database.


Step 3: Select the Notes Form to MonitorA list of forms within the selected database appears. These are the formsyou will use to display external system data. Select a single form that youwant to monitor from the list shown.


Step 4: Select the Lotus Connection for the Data SourceSelect the Connection for external data source you want to monitor fromthose available in the Select Connection dialog box, shown below.

When you have selected a connection and there is more than one table inthe external database, another database opens asking you to select a table inthe external database. See the illustration below.



Step 5: Map Data Field(s)After specifying the external data source and providing any requiredconnectivity information, such as User Name and Password, the Data FieldMapping dialog box appears. Use this dialog box to map data field(s)between the Domino application and the external data source.

Note In general, if there are unmapped columns in the Virtual Documentstable, which do not accept NULLs, you will receive a NULL assignmenterror when creating a new record. The exact wording of this error dependson the Connector you are using.

Step 6: Create the External Key Table (optional)If the Notes control fields exist in your external data source, the fields willbe mapped automatically. If they do not exist, you must create them usingthe Create External Key Table function. This procedure is described in thesection entitled “Creating an External Key Table” later in this chapter.


Step 7: Name the Activity DocumentWhen prompted, enter a unique name and click OK.


Click OK. The Virtual Documents Activity document appears, showingyour selections. The numbers in the document correspond to the majorsteps the User Assistant uses to create the Virtual Documents Activity.


Step 8: Select OptionsSelect the specific options that you want for this Virtual DocumentsActivity. See “Virtual Documents Options,” in this chapter for a fulldescription.

Step 9: Select Scheduling OptionsSelect how you want to control the scheduling of the Virtual DocumentsActivity. See the “Scheduling” section later in this chapter for moreinformation.

Step 10: Save and Close the DocumentChoose File - Save to save the activity. Choose File - Close to close theVirtual Documents Activity document and return to the LEI Administrator.

Step 11: Process the Virtual Documents ActivityIn the LEI Administrator’s Activity View, select the Virtual DocumentsActivity and then click the Start button to run it.

Note You can process the activity using the Start and Stop buttons in theAction bar of an Activities View in the LEI Administrator. When you select“Auto Start” in the Scheduling section of the Activity Document, the VirtualDocuments Activity is established each time that the server starts. See theScheduling section for more information.

To optionally stop a Virtual Documents Activity, select the activity name inthe Activities view and click the Stop button.

Note If you enable the Virtualize External System Data option (default),the activity will first search for and then virtualize all external system tablerecords that have not yet been virtualized. If the table contains many suchrecords, this action can take several minutes or even more depending ontable size and network load. Although the LEI Administrator will indicatethat the activity has started, while it is virtualizing external system tablerecords, virtual documents not be accessible. Check the activity log progress(periodically refresh your view by pressing the F9 key) and results of thisvirtualization process. When it is complete, a message will appear and theactivity will become accessible.


Creating a Virtual Documents Activity without the User AssistantYou can optionally enable the User Assistant to prompt you the through thecreation of a new Virtual Documents Activity. You can toggle the UserAssistant on and off using the Help option in the Navigator panel of theAdministrator. If you disable the User Assistant, a blank Activity Documentis opened for you to define the activity.

This section describes how to create a Virtual Documents Activity withoutusing the User Assistant. For options not described in these steps, see thechapters entitled “LEI Administrator” and “Introduction to LEI Activities.”

Step 1: Open the Activity DocumentClick the Add Activity icon. The Virtual Documents Activity Documentappears.


Step 3: Select the Domino Application and the Form to MonitorClick the down-arrow icon in the Domino application section. A list ofdatabases appears. Select the database that contains the Domino applicationthat you want to monitor. You are also prompted for a form name.

Note When the list is large, you can scroll down the list to find the Dominoapplication (nsf) you want to select. However, if the list is too large to becompletely accommodated by scrolling, an overflow message appears at thebottom of the list (<overflow…>) and a box appears under the list, whichyou use to type in the exact name of the .nsf file you want to use. For moreinformation on browsing and browsing requirements, see “Browsing” in thechapter entitled “LEI Administrator.”

Note Real time monitoring uses the Notes replica id of the applicationdatabase. A Virtual Documents Activity does not distinguish between thedatabases that share the same replica id. Databases have the same replica idwhen they are replicas of each other and when one database is createdusing the operating system to copy an existing database.




Step 5: MappingClick the down-arrow icon in the Mapping section. The field mappingdialog box appears. Use this dialog box to map the data fields between theDomino application and the external data source.

Note If there are unmapped columns in the Virtual Documents table,which do not accept NULLs, you will receive a NULL assignment errorwhen creating a new record. The exact wording of this error depends on theConnector you are using.

Step 6: Create the External Key Table (optional)If the Notes control fields exist in your external data source, the fields willbe mapped automatically. If they do not exist, you must create them usingthe Create External Key Table function. This procedure is described in thesection entitled “Creating an External Key Table” later in this chapter.

Step 7: Select Options and Event OptionsSelect the options and the event options you want on the “Options” and“Event Options” tabs in the document. See the section “Virtual DocumentsActivity Options and Event Options” later in this chapter for moreinformation.

Step 8: Select Scheduling OptionsSelect how you want to control the scheduling of the Virtual DocumentsActivity. The options are Manual, AutoStart, and Custom. See the“Scheduling” section later in this chapter for more information.

Step 9: Save and Close the DocumentChoose File - Save to save the Activity Document. Choose File - Close toclose the Activity Document and return to the LEI Administrator.


Step 10: Process the Virtual Documents ActivityIn the LEI Administrator’s Activity View, select the Virtual DocumentsActivity and then click the Start button to run it.

Note You can process the activity using the Start and Stop buttons in theAction bar of an Activities View in the LEI Administrator. When you select“Auto Start” in the Scheduling section of the Activity Document, the VirtualDocuments Activity is established each time that the server starts. See theScheduling section for more information.

To optionally stop a Virtual Documents Activity, select the activity name inthe Activities view and click the Stop button.

Note If you enable the Virtualize External System Data option (default),the activity will first search for and then virtualize all external system tablerecords that have not yet been virtualized. If the table contains many suchrecords, this action can take several minutes or even more depending ontable size and network load. Although the LEI Administrator will indicatethat the activity has started, while it is virtualizing external system tablerecords, virtual documents not be accessible. Check the activity log progress(periodically refresh your view by pressing the F9 key) and results of thisvirtualization process. When it is complete, a message will appear and theactivity will become accessible.

Virtual Documents Activity Document OptionsOnce you have specified the Domino application, the connection you wantto use, and set up mapping, there are a number of options for you toconsider in setting up the activity.

The options are broken down into two areas: Options and Event Options.

• The Options tab contains the following three areas.

• General Options


• Virtual Attachments

• The Event Options tab contains the following four areas.

• Create

• Open

• Update

• Delete


See the chapter entitled “Introduction to LEI Activities” for a description ofthe following sections that are common to all Activity Documents:

• Activity Name

• Scheduling

• Category

• Comments

Virtual Documents Options TabThe Options tab contains three tabs — General Options, IntegratedCredentials, and Virtual Attachments.

General OptionsThe General Options section provides options that can be applied to theVirtual Documents Activity regardless of the type of event that the activitymonitors. Each of the General Options is described after the illustration.

Note To use Virtual Documents you must set up four fields in the externaldata source. See “Required External System Fields for Virtual DocumentsActivities” earlier in this chapter for details.


continued

If selected (default), the external data row will not be removedbut will only be internally marked as deleted and will no longerbe accessible as a Virtual Document in Notes. These rows maybe periodically purged and removed if purging is enabled forthe Notes databases.

If disabled, the external data row will always be removed on aVirtual Document delete. However, this deletion will not bereplicated to other databases by Domino.

MaintainDeletion Stubs

Select either of two options:

Keys Are in Connector Table — If you select this option, the keyfields must be present in the external database table.

Use External Key Table — Select this option to use virtual viewfacilities without modifying the external system database table.The required Notes fields are stored in an external table thatincludes key fields that are used to match the rows with the datatable.

If you want to create an external key table, you must select thisoption.

When you select this option, two additional choices becomeavailable: “Key Table Name” and “Key Fields”, both of whichmust also be specified in order to create an external key table.

wwww Key Table Name — The name of the external table whichcontains the required fields to synchronize with the Dominodatabase. This is a separate table from the Data Source table.If using this field in conjunction with creating an external keytable, enter a new name here - not the name of an existingtable.

wwww Keys Field(s) — Fields that map to unique records in the datatable.

Note You cannot run a Virtual Documents Activity, using theExternal Key Table option, if the connection is to ODBC usingData Direct 3.5 Lotus-branded drivers.

Note See the section entitled “Creating an External Key Table”for complete step-by-step instructions.

Key Table Option



continued

Prevent data loss — Write an error to the log for any data lossresulting from a data type conversion.

Allow precision loss — Do not report loss of numerical orDATETIME precision as a result of a data type conversion. Thisallows some loss of precision without stopping the transfer. Thisoption is the default.

Allow precision loss & truncation of text — Enable this option tohave LEI allow precision loss as well as truncation of text datawhen necessary to conform to field lengths in the externaldatabase.

Data Integrity

This option sets the maximum number of connections to theexternal database that can be open to service concurrent userrequests simultaneously. The minimum number of connectionsfor Virtual Documents is 2. If you experience significant delays,you can increase this number.

LEI opens one connection to the external data source when thefirst Domino application event occurs. If two or more eventsoccur simultaneously, additional connections are made, up tothe maximum number of connections specified by this option.

When the maximum number of connections is reached,subsequent events are queued and occur when each precedingevent is serviced. Each connection lasts only as long as necessaryto read from or write data to the external data source.

While the connection is persistent, the time required to serviceeach event is minimal and depends on the amount of data beingread or written. The maximum number of connections,therefore, does not need to be very large to service multipleevents.

Max.Connections

Select Virtualize External System Data to enable this activity toautomatically virtualize external database system data when theactivity starts and at periodic intervals where new data is addedthrough an external (non-Notes) client.

Note Only one Virtual Document Activity should have thisoption enabled per external data table.

When you select the Virtualize External System Data option, theRefresh Frequency option becomes available.

wwww Refresh Frequency: Frequency that new records fromnon-Notes sources are inserted in the view. The choices areminutes, hours, and days. The default is once every hour.

VirtualizeExternal SystemData



Select the option you want to use to convert the Notes new linedelimiter to a new line delimiter in another system.

New LineDelimiter forConnection

This option affects any trailing spaces that exist in the Text fieldsof the external data.

Trim spaces on all fields — Select this setting to trim trailingspaces only from data fields, not from the key fields. (Default)

Do not trim spaces on any fields — Select this option to leavetrailing spaces in all fields.

Trailing spaces may be required to ensure matching of fieldsbetween Notes and the external data.

Note When data is put into external system fields of fixedlength and then retrieved, the connection with the externalsystem may be lost because the external system has padded thedata with spaces to fit the fixed length of the field. If this occurs,use either a variable length field (VARCHAR) in the externalsystem database, or enable the “Trim spaces on all non-keyfields” option.

Trim TrailingSpaces


Creating an External Key TableThis section describes how to create and use an external table for therequired additional external system columns. It also describes therestrictions involved in this approach.

Although modifying an existing data table, or creating a data table with theadditional needed columns, is the most logical way to enable VirtualDocuments to access external system data, it may not always be desirable.Using an External Key Table eliminates the need to modify the existing datatable but also requires additional steps. If you choose to store these valuesin a separate external key table, use this procedure.

The Virtual Documents Activity requires that the data source contain eithera dedicated table or fields in an existing table to store Notes controlinformation. Since no information about the document is stored in Notes,there needs to be a place to store the document universal ID, creationdate/time, and other system values.


The following steps describe how to create an external key table using aVirtual Documents Activity.

1. Determine whether you will create your data table or use an existingone. The data table must contain one or more columns that form aunique key set for each row of data. More than one column can be usedto achieve unique values.

As with the method where you add the four required columns(EINOTEID, EIUNID, EIMODIFIED, and EINOTEPROPS) to anexisting data table, an external key table must also contain thesecolumns, in addition to at least one key column from the data table. Thekey column(s) allows the external key table to mesh with the same keycolumns in the data table. The key column(s) should have the samename and data type as the counterpart(s) in the data table. The ActivityDocument itself helps aid you in specifying these required conditions.

2. Create a new Virtual Documents Activity using the Add Activitybutton in the LEI Administrator action bar.

See either “Creating a Virtual Documents Activity Using the UserAssistant” or “Creating a Virtual Documents Activity Without the UserAssistant” later in this chapter for complete instructions.

3. Click the “Options” tab on the “General Options” tab in the middle ofthe Activity Document.


4. Select the Key Table Option “Use External Key Table” check box. As aresult, the “Key Table Name” and “Key Field(s)” option appear. Youmust enter data in these fields now.

5. In the “Key table name” field, enter a table name now.

6. In the “Key field(s)” field, choose at least one key column name(s) fromthe resultant list.

To test the required fields, see the section entitled “Using and Testingthe Required Tables” for more information.

Note Certain fields should be indexed at the external system toimprove performance. See the section entitled “Indexing to IncreasePerformance” for more information.

7. Select the Create External Key Table button that appears just above theKey Table Option item on the Activity Document.

8. The Create Key Table dialog appears, enabling you to select the optionsthat will set an optimal size limit for some fields and create indexes asappropriate for others. Complete the form using the descriptionspresented below.


The bottom part of the dialog contains questions to help configure thekey table appropriately for your environment. These questions varydepending on which Lotus Connector is being used for the activity.

Note If the user ID and password stored in the Connection Documentdon’t have sufficient access to create tables in your destinationdatabase, uncheck the “Use Connector Credentials” option. This letsyou enter a different user ID and password that will only be used forthis one operation. This login information will not be stored in the LEIAdministrator database.

The Create Key Table dialog box contains the following fields:

• Table Name — This field displays the table name that you entered inthe Key Table Name field in the General Options section of theActivity Document.

Note You must include the owner name in the first part of the TableName entry. For example, to create a table named EMPTRANSFERwith an owner name of DB2ADMIN, you would enterDB2ADMIN.EMPTRANSFER in the Table Name field on the CreateAttachment Table form.


• Optimization Questions — Depending on the type of Lotusconnection that you specify on your Virtual Documents ActivityDocument, optimization questions will appear in your dialog box.However, when connecting to Oracle 8, DB2, or OLE DB, it is notnecessary to specify the size of the system field area(EINOTEPROPS). In such instances, the optimization questions and“System field storage … bytes” field will not be present in the dialogbox.

These questions are used to calculate an optimal size for theEINOTEPROPS field and to decide which fields should be indexedfor best performance. Depending on your answers, LEI will calculatea suggested value for the field size limit. However, you may overridethis suggestion by entering a different value in the “System fieldstorage … bytes” field in this dialog. If you leave this field blank, the“suggested” value will be used.


• System field storage — Use this to override the suggested size for theEINOTEPROPS field. See the description for Optimization Questionsabove for more information.

9. When you have completed the form using the dialog box descriptionsabove, click OK in the upper right of the form to create the key table.


For information about using these fields as stored procedure arguments, seethe section entitled “Using Stored Procedures in Virtual DocumentsEvents.”

For information about which fields will be indexed by the table creationtool, refer to the section entitled “Usage Requirements for VirtualDocuments and Virtual Attachments.”

ConsiderationsWhen creating Virtual Documents with the External Key Table option, thefollowing considerations apply:


• You cannot run a Virtual Documents Activity using the External KeyTable option if the connection is to ODBC using Data Direct 3.5Lotus-branded drivers.

• You must enable writeback in order to modify a key using an externalkey table. Modification of non-key fields does not require writeback.Alternatively, you can delete the record and then recreate it with a newkey value.

• The data table and the External Key Table must reside on the sameexternal system data source (sameconnector/server/database/userid/password, different table name).

• If rows are deleted from the data table by another application and thecorresponding entry in the ID table is not deleted, you will receive“unable to retrieve external record” errors when you attempt to accessthat Virtual Document. See the section entitled, “Special ConsiderationsWhen Deleting Virtual Attachments” for more information.

• If there are data rows with duplicate keys, only one ID table entry willbe created, only the first data row will be retrieved on open, and bothrecords will be modified on delete and update.

• For maximum performance, always index the data table key columns.See the section entitled “Indexing to Increase Performance” for moreinformation.

• Regardless of whether the corresponding key columns in the data tablemay be constrained to not allow duplicate values, do not impose thatsetting on the key columns in the external key table. In the external keytable, key columns should be set to allow duplicate values.

• There is no support currently for adding the four required columns(EINOTEID, EIUNID, EIMODIFIED, and EINOTEPROPS) to anexisting table from the Activity Document. Most external data sourcesdo not permit us to do this. If you would prefer to add the fields to anexisting table, you might create the external table first, then use yourrelational database configuration tool to copy fields to the table youwant them to appear in. Notice which columns are indexed in theexternal key table and retain those indexes when you copy the fields.Alternatively, you can create a new table with the new columns andthen use a Direct Transfer Activity to copy the data from the old table tothe new table.


Integrated CredentialsUser credentials for the external system are looked up when the IntegratedCredentials options is selected. The credentials are used to connect to theexternal system. This increases Domino security by integrating it with thesecurity already in place for the external system.

Note The integrated credentials database is described in the “Introductionto Activities” chapter of this document; see the section entitled “IntegratedCredentials Database” for information about creating and using anintegrated credentials database.

Note If you are using integrated credentials with Virtual Documentsthrough an HTTP client, you also need a server credential document.

Note When using integrated credentials with an HTTP client, if the .nsfdoes not prompt for a user name and password, the user is logged in as“Anonymous.” As a result, a credential entry for “Anonymous” may beneeded.

Each of the Integrated Credentials options is described after the illustration.


When you select this option the form expands toinclude the following options:

Missing Credentials — In case of a credentialslookup failure, either the operation can fail (this isthe default action) or default credentials in theactivity can be used.

Credentials DB Filepath — The name of thecredentials database to be used for storing Notesuser names and corresponding external systemscredentials. The path is specified relative to the LEIdirectory (for example leidir).

Note You must have created this database usingthe template leicred.ntf. See “Setting Up and UsingIntegrated Credentials” in the Introduction toActivities chapter of this document.

Connection Cache Size — Maximum number ofdistinct credentials active at one time.

Note If the credentials used to access the externaldatabase system do not have write privileges tothe tables, Notes users that attempt to modify(delete, update, create) documents will receive anerror.

Lookup Credentials

Use the user ID and password that was enteredinto the Connection Document you are using inthis activity.

Use Connector Credentials

DescriptionIntegrated Credentials Options


Integrated Credentials and Server to Server ReplicationIn order to perform server to server replication in conjunction withintegrated credentials, you must add the server ID of the server beingreplicated with to the integrated credentials database. For example, if youwant to replicate a Virtual Documents or Virtual Fields-enabled databaseon Server A to Server B, you must add Server B’s server ID to the integratedcredentials database on Server A.



Virtual AttachmentsThe Virtual Attachments feature allows you to use Notes to addattachments to the external system database. File attachments will be storedin the external system rather than in your Domino application. Once added,they can be accessed through the virtual views.

Note Storing the file name and Notes ID makes identification and retrievalof the attachments easier but requires additional columns in the externalsystem table.

The list of required and optional Virtual Attachment columns is as follows:

RequiredEICONTENTS

OptionalEIFILENAME

OptionalEIUNID

RequiredEIFILESIZE

RequiredEIFILEID

RequiredEIDBID

Required or OptionalColumn Name

You do not need to include the EIUNID or EIFILENAME fields in theattachments table. They are not needed by LEI, but LEI maintains them ifthey are provided. These fields allow external database applications tomore easily recognize and access the data outside of LEI/Domino. EIUNIDis the noteid value that corresponds to the EIUNID field in the row of thedata/key table. EIFILENAME is the name of the attachment as specified inthe note. You can control this functionality using the Store Optional Fieldsoption on the Activity Document.

An important restriction is that the virtual attachments table must be in thesame external system and in the same database as the external system databeing accessed by the activity. The virtual attachments table cannot residein a different external system or database than the one being used by theVirtual Documents Activity. This is because the same ConnectionDocument is used to access the external system.


The Virtual Attachments feature allows you to add attachments to virtualdocuments as you would to a native Notes document. The exception is thatfile attachments are stored in the external system rather than in yourDomino application. The attachment data is stored in a binary field in anexternal system table that you create. Other columns in the external systemtable store key data, which enables the activity to locate a specificattachment. A single table can be used for multiple Virtual DocumentsActivities. The following considerations are helpful as you use this feature.

• You must select the Virtualize Attachments option when you useattachments in a Virtual Document. You cannot save an attachment in aVirtual Documents Activity unless it is virtualized. If you do not, yourattachments will not be saved.

• If the “fixup” utility is run on the Notes database while a monitoreddocument is open, you must either close and reopen document or savethe document to access any restored Virtual Attachments. Forinformation about “fixup” see the Domino server documentation.

Select this option to add the attachment file name and itsNotes ID to the attachment table. This option is notrequired.

Note Storing the file name and Notes ID makesidentification and retrieval of the attachments easier butrequires additional columns in the external system table.

Additional data

Specify a separate table for the contents of theattachments.

In addition to the contents of the attachments, this locationalso contains a locator key. Optionally, the file name andNotes ID may be stored as an additional data element.Select “Additional data” for this option.

Note When you create a virtual attachment table inSybase, the column names must be in upper case.

Note See the section entitled “Creating a VirtualAttachments Table” for complete step-by-step instructions.

Attachment table(Required if“Attachments” isselected.)

Virtualize Attachments — You must select this option tobe able to store attachments with your virtual documents.Enabling this option requires that you create and specifyan external system table to contain the contents of theattachment.

Note You must specify an attachment table in order tocreate a virtual attachments table.

Attachments

DescriptionVirtual AttachmentsOptions


Indexing Fields for Increased PerformanceIf you are using Virtual Attachments, the Virtual Attachment Table shouldbe indexed on EIFILEID. In addition, the Virtual Attachment Table EIDBIDcolumn should be indexed if the table supports multiple databases. It isused by multiple Virtual Documents activities, some of which monitorforms from different Domino databases.

Fields and Data TypesThe following table describes the necessary fields and data types that arerequired for the attachment table at the external system as well as the fieldsthat are required on the Notes form.

OLE Object

IMAGEBLOB(1048576)

IMAGEBYTELONG RAWEICONTENTSrequired)

TEXT(255)

VARCHAR(255)

VARCHAR(255)

VARCHAR(255)

VARCHAR(255)

VARCHAR2(255)

EIFILENAME(optional)

TEXT(32)

CHAR(32)

CHAR(32)

CHAR(32)

CHAR(32)


EIUNID[d](optional)

NUMBERLONGINTEGER

INTINTEGERINT INT NUMBER(8)

EIFILESIZE [c] (required)

NUMBERINTEGER

INTINTEGERINTINTNUMBEREIFILEID**(required)

TEXT(16)

CHAR(32)

CHARACTER(16)

CHAR(16)

CHAR(16)

VARCHAR2(16)or CHAR(16)

EIDBID**(required)


DB2 [b]Sybase [a]InformixOracle

External System Data Types AttachmentTable Fields


a) In case sensitive RDBMS’s, such as Sybase, column names must be inupper case, for example, EIUNID.




d) EIUNID is a DWORD, or an unsigned 32-bit integer. According to theformula 2^n - 1, this gives a maximum EIUNID of 4,294,967,295 whichrequires 10 digits.

Specifying the Attachment Table and SchemaBy default, if a schema is not specified for the virtual attachment table, theuser making the connection is used by default. For example, if the user isTESTONE and the schema is DBSOURCE, the user will be taken as theschema, TESTONE.MY_TABLE. If the virtual attachment table is pickedfrom the selection dialog, the schema name is added as a prefix. However,if the user types the table name in by hand and there is a difference betweenthe schema and the connection user, he must type the schema name as aprefix, for example, DBSOURCE.MY_TABLE.

Any attachments that were not entered into the external system through theVirtual Attachment process will not be accessible through either VirtualFields or Virtual Documents. For example, if you added attachments to theexternal system database through another process, for example SQLcommands, you cannot access them through Virtual Fields or VirtualDocuments. You can create the table using SQL commands.

Creating a Virtual Attachments TableIn the Virtual Documents and Virtual Fields Activity Documents, you canconfigure the activity to use a relational table to store file attachments asbinary objects by creating a virtual attachments table.

1. Click the “Virtual Attachments” tab in the middle of the ActivityDocument.


2. Click the Attachments: Virtualize Attachments option.

3. In the Attachment table field, enter the name of the table that you wantto create.

4. Optionally specify that you wish to store optional fields.

5. Click the Create Virtual Attachments Table button.


6. The Create Attachment Table dialog appears, enabling you to select theoptions that will set an optimal size limit for some fields and createindexes as appropriate for others. Complete the form using thedescriptions presented below.

• Table Name — This field displays the table name that you entered inthe “Attachment table name” field of the Activity Document.

Note You must include the owner name in the first part of the Table Name entry. For example, to create a table namedEMPTRANSFER with an owner name of DB2ADMIN, you would enter DB2ADMIN.EMPTRANSFER in the Table Name field on theCreate Attachment Table form.


7. When you have completed the form using the dialog box descriptionsabove, click OK in the upper right of the form to continue.


Note If the table already exists, you will prompted whether tooverwrite it. If you answer Yes, the existing table and all the data in itare erased. Since most connection types don’t allow existing tables tohave fields added or field properties adjusted by an external program,


changing existing attachment tables that were incorrectly created is notsupported.

For information about which fields will be indexed by the table creationtool, see the section in this chapter entitled “Virtual Attachments in VirtualDocuments Activities.”

Event Options TabThe Create, Open, Update, and Delete options are available from the EventOptions tab. They provide many options that depend on the type of eventthe Virtual Documents Activity monitors. The monitored events occur inthe Notes form that you specified in this Activity Document. Each of theoptions is described in the tables on the following pages.

Unlike Virtual Fields activities, Virtual Documents Activities alwaysprocess these four basic form events.

Create OptionsWhen monitoring Document Create Events, several options are availabledepending on the choices you make. A description of each of the optionsfollows the illustration.

continued

Executes a Notes formula language statement before the documentdata is stored. You can use this option to modify existing fields orto compute values for additional fields. For example:

FIELD LASTNAME:=@if(LASTNAME = ““;“NA“;LASTNAME);””

Note If you are connecting to an Oracle external system and youmust use a text field(s) of fixed length as a key field(s), use aformula filter to pad the specific field to the correct length. See theLotus Connector for Oracle 7 or 8 information in Lotus Connectorsand Connectivity Guide for more information.

Pre-CreateFormula



Domino Application — Specifies the fields in the Dominoapplication (Notes document) that will receive the stored procedureoutput.

Lotus Connection — Specifies the fields from the external systemthat contain the stored procedure output. The first field from theexternal system maps to the first destination field, the secondexternal system field to the second destination field, and so on.

Note These fields must be specified in the “Mapping” section ofthe Activity document.


Enable Procedure Output — This option is available only if a storedprocedure has been specified in the “Stored Procedure” field. Whenthis option is selected, it opens up the “Stored Procedure OutputMapping” section of the Activity document, where you enter inputand output field names.

This option enables the return of data from a stored procedure inthe external system to the Domino application (that is, the Notesdocument). The Activity’s key(s) and field(s) are supplied to thestored procedure as input parameters.

To see the arguments that will be passed to the stored procedure,type the stored procedure name in this field and then press F9. Thefields that will be passed to the stored procedure are displayed nextto the stored procedure name.

Note Only the Lotus Connector for DB2 supports outputparameters.


Executes a stored procedure in the external data source to storedata that has been entered into the Notes document. The field(s) aresupplied to the stored procedure as input parameters.

To specify the stored procedure and see the parameters that will bepassed to the stored procedure and their order, type the storedprocedure name in this field and then press F9. The fields that willbe passed to the stored procedure are displayed next to the storedprocedure name. Domino/LEI supports stored procedurebrowsing.

In a Virtual Documents Activity, the required parameterEINOTEID, one of the four required columns (EINOTEID, EIUNID,EIMODIFIED, and EINOTEPROPS) also appears.

Note When you use stored procedures with Virtual Documents,you must add the EINOTEID parameters to the stored procedure atthe external system. See the section “Using Stored Procedures inVirtual Documents Events” for more information.


StoredProcedure



Open OptionsWhen monitoring Document Open Events, several options are availabledepending on the choices you make. A description of each of the optionsfollows the illustration.

These fields are visible only if “Stored Procedure Output” in either aCreate or an Update event has been selected, see either Create orUpdate event for more information.


Executes a stored procedure in the external data source to determinethe data that will be retrieved into the Notes document.

To see the arguments that will be passed to the stored procedure,type the name of the stored procedure in this field or select the storedprocedure from the drop down list and then press F9.

In the case of Virtual Documents of the four required fields, only theEINOTEID field is necessary as an input field. The rest of the fieldsare output fields. These are specified according to the externalsystem.

For Connectors that support procedure output parameters, the keyfields are passed as input/output parameters and the other fields arepassed as output parameters.

Note Domino/LEI supports stored procedure browsing.

Note See the “LEI and Data” appendix for error situations you mayencounter using Sybase or OLE DB stored procedures that return aresult set.

StoredProcedure

Executes a Notes formula immediately after data is retrieved fromthe external system. You can use this option to compute additionalfields or modify existing fields. For example:

FIELD FIRSTNAME := @if(FIRSTNAME =“Al“;“Albert“;FIRSTNAME);””

Note Do not use Post-Open Formulas when using conflict detection.

Post-OpenFormula



Update OptionsWhen monitoring Document Update Events, several options are availabledepending on the choices you make. A description of each of the optionsfollows the illustration.

continued

When a document is updated, you can use this option toexecute a Notes formula before the data is saved in theexternal system. The field(s) are supplied to the storedprocedure as input parameters.

To specify the stored procedure and see the parametersthat will be passed to the stored procedure and their order,type the stored procedure name in this field and then pressF9. The fields that will be passed to the stored procedureare displayed next to the stored procedure name.Domino/LEI supports stored procedure browsing.

In a Virtual Documents Activity, the required parameterEINOTEID, one of the four required columns (EINOTEID,EIUNID, EIMODIFIED, and EINOTEPROPS) also appears.

Note See the “LEI and Data” appendix for error situationsyou may encounter using Sybase or OLE DB storedprocedures that return a result set.

Stored Procedure

When a Notes document is updated, this option executes aNotes formula statement before the data is saved in theexternal database.

Pre-Update Formula



Domino Application — Specify the fields in the Dominoapplication (Notes document) that will receive the storedprocedure output.

Lotus Connection — Specify the fields from the externalsystem that contain the stored procedure output. The firstfield from the external system maps to the first destinationfield, the second external system field to the seconddestination field, and so on.

Note These fields must be specified in the “Mapping”section of the activity.


Only Update Changed Fields — Causes the VirtualDocuments Activity to not update fields in the externaldata source unless the corresponding fields in the Notesdocument have been edited.

Use this option if you have triggers in the external systemthat monitor updates to individual columns of a table.

Field Level Updates

Check External Data for Changes — Ensures that theexternal data has not changed since the Notes documentwas opened. If it has changed, an update to the externaldata source will fail.

If this option is enabled and if you make changes to data ina Notes document and then save the document, you mustexit the document before making any more changes —even though you have saved the document.

Note When using an HTTP server to access documents,“Conflict Detection” is not supported.

Conflict Detection

Enable Procedure Output — This option is available only ifa stored procedure has been specified in the “StoredProcedure” field. When this option is selected, it opens the“Stored Procedure Output Mapping” section, where youenter input and output field names.

This option enables the return of data from a storedprocedure in the external system to the Domino application(Notes document). The activity’s key(s) and field(s) aresupplied to the stored procedure as input parameters.

To see the arguments that will be passed to the storedprocedure, type the stored procedure name in this fieldand then press F9. The fields that will be passed to thestored procedure are displayed next to the storedprocedure name.

Note Only the Lotus Connector for DB2 supports outputparameters.

Stored ProcedureOutput



Delete OptionsWhen monitoring Document deletion Events, several options are availabledepending on the choices you make. A description of each of the optionsfollows the illustration.

continued

Notes formula language statement to execute on the Notesdocument immediately prior to the deletion in the externaldata source.

Here is an example that sends an E-mail containinginformation about a deleted document:

FIELD LASTNAME:=LASTNAME;

FIELD FIRSTNAME:=FIRSTNAME;

@MailSend(“John Q Public“;““;““;“Doc Deleted“;“Docdeleted from MyDatabase w/ Firstname/Lastnameof:“;FIRSTNAME:LASTNAME);””

Note It may be necessary to specify that activity data besaved in the Notes document; otherwise, the specifiedformula may access the field values after they’ve beendeleted. If this were the case for the example above,FIRSTNAME and LASTNAME would be empty. To specifythat activity data be saved, display the Data Storage tabunder the General Options tab, and select the “Leaveall/selected realtime fields in document” option.

Pre-Delete Formula

DescriptionDelete Options


These fields are visible only if “Stored Procedure Output”in either a Create or an Update event has been selected. Seeeither Create or Update event for more information.


When a document is deleted this option executes a storedprocedure in the external data source to remove the datarelated to the document.


In the case of Virtual Documents of the four required fields,only the EINOTEID field is necessary as an input field. Therest of the fields are output fields. These are specifiedaccording to the external system.

For Connectors that support procedure output parameters,the key fields are passed as input/output parameters andthe other fields are passed as output parameters.

Note When you use stored procedures with VirtualDocuments, you must add additional parameters to thestored procedure. See the section “Using Stored Proceduresin Virtual Documents Events” for more information.

Note See the “LEI and Data” appendix for error situationsyou may encounter using stored procedures that return aresult set with Sybase or OLE DB.

Stored Procedure

DescriptionDelete Options

Using Stored Procedures in Virtual Documents EventsAny of the four basic events handled by the Virtual Documents Activity(Create, Open, Update, Delete) can, instead, be handled through a storedprocedure defined in the external system. These procedures can addspecific external logic to the operation, such as modifying data fields, oradd reporting functionality for example. However, if you use a storedprocedure, you must follow certain important guidelines for writing thestored procedure.


Currently you cannot use an external key table with stored procedures.

First, EINOTEID must always be one of the parameters to the storedprocedure. This parameter corresponds to one of the additional columnsrequired in the external system table by the Virtual Document Activity. TheEINOTEID parameter must be used as the unique key to access the externalsystem table from within the stored procedure. See the section “RequiredExternal System Fields for Virtual Document Activities” for moreinformation about this field and the data type it requires.

Second, for all the events except the delete event, ALL the external systemtable data fields mapped in the Virtual Document Activity must be presentas parameters. No other parameters are allowed. For a delete event storedprocedure, only the EINOTEID is required.

Third, the stored procedure must perform an operation consistent with theVirtual Document event to which it is associated. For example, an Openstored procedure must use the EINOTEID as a key to perform a Selectoperation. A Create stored procedure must insert a new row into the table.The procedure may alter data, access other tables, and perform otheroperations, but the operation on the external system table specified in theVirtual Documents Activity must be consistent with the event.

Note The EINOTEID parameter value must never be altered in any way.

Finally, special care must be taken with Delete stored procedures. If thestored procedure elects to actually remove the external system table row,using the EINOTEID as the key, Domino will lose the ability to replicate theVirtual Document deletion to replica databases. If replicating VirtualDocument deletions is required, do not allow the stored procedure toactually remove the row. Subsequent internal operations will mark the rowas deleted to Domino, but will leave it intact in the table. You may still use adelete stored procedure to simply perform a reporting operation or someother housekeeping operation for example. If you only wish to use thedelete stored procedure to remove the external system row, you can insteadsimply disable the “Maintain Deletion Stubs” option in the VirtualDocuments Activity.

The following summarizes the stored procedure parameter requirements:

For Create or Update events, in addition to the mapped data fields, storedprocedures must accept the EINOTEID field as an input parameter.


For Open events, in addition to the mapped data fields, stored proceduresmust accept the EINOTEID field as an input/output parameter.

For Delete events, only the EINOTEID must be mapped as an inputparameter.

There is nothing you have to do to ensure that EINOTEID is being mappedother than be certain that the name and data type is correct.

Stored Procedure ExamplesHere are some simple DB2 stored procedure examples that illustrate the useof the EINOTEID parameter. These examples assume that the VirtualDocument Activity has only two mapped data fields: EMPNO andSALARY.

OPEN ExampleHere is a DB2 stored procedure open example:

CREATE PROCEDURE MRL_EMP_EIVD_OPEN (INOUT EINOTEID INT, OUTEMPNO INT, OUT SALARY INT)

LANGUAGE SQL

----------------------------------------------------------------------

-- SQL Stored Procedure

----------------------------------------------------------------------

P1: BEGIN

DECLARE KeyVar INT;

SET KeyVar = EINOTEID;

SELECT EMPNO, (SALARY * 2) AS SALARY, EINOTEID

INTO EMPNO, SALARY

FROM MRL_EMP_EIVD

WHERE MRL_EMP_EIVD.EINOTEID = KeyVar;

END P1


UPDATE ExampleHere is a DB2 stored procedure update example:

CREATE PROCEDURE MRL_EMP_EIVD_UPDATE (IN EINOTEID INT, INEMPNO INT, IN SALARY INT)

LANGUAGE SQL

------------------------------------------------------------------------


------------------------------------------------------------------------

P1: BEGIN

DECLARE KeyVar INT;

DECLARE VarEmpno INT;

DECLARE VarSalary INT;


SET VarEmpno = EMPNO;

SET VarSalary = SALARY;

UPDATE MRL_EMP_EIVD

SET EMPNO=VarEmpno, SALARY=VarSalary*2


END P1

UPDATE Example (with output parameters)Here is a DB2 stored procedure update example that also has outputparameters:

CREATE PROCEDURE MRL_EMP_EIVD_UPDATE_OUTPARAM (IN EINOTEIDINT, INOUT EMPNO INT, INOUT SALARY INT)

LANGUAGE SQL

------------------------------------------------------------------------


------------------------------------------------------------------------

P1: BEGIN

DECLARE KeyVar INT;






SET VarSalary = SALARY;

UPDATE MRL_EMP_EIVD

SET EMPNO=VarEmpno, SALARY=VarSalary*2


SET EMPNO = VarEmpno;

SET SALARY = VarSalary*2;

END P1

CREATE ExampleHere is a DB2 stored procedure create example:

CREATE PROCEDURE MRL_EMP_EIVD_CREATE_OUTPARAM (IN EINOTEIDINT, IN EMPNO INT, IN SALARY INT)

LANGUAGE SQL

------------------------------------------------------------------------


------------------------------------------------------------------------

P1: BEGIN

DECLARE KeyVar INT;





SET VarSalary = SALARY * 2;

INSERT INTO MRL_EMP_EIVD (EINOTEID, EMPNO, SALARY)

VALUES (KeyVar, VarEmpno, VarSalary);

END P1


CREATE Example (with output parameters)Here is a DB2 stored procedure create example that also has outputparameters:

CREATE PROCEDURE MRL_EMP_EIVD_CREATE_OUTPARAM (IN EINOTEIDINT, INOUT EMPNO INT, INOUT SALARY INT)

LANGUAGE SQL

------------------------------------------------------------------------


------------------------------------------------------------------------

P1: BEGIN

DECLARE KeyVar INT;





SET VarSalary = SALARY * 2;

INSERT INTO MRL_EMP_EIVD (EINOTEID, EMPNO, SALARY)

VALUES (KeyVar, VarEmpno, VarSalary);

SET EMPNO = VarEmpno;

SET SALARY = VarSalary;

END P1

DELETE ExampleHere is a DB2 stored procedure open example:

CREATE PROCEDURE MRL_EMP_EIVD_DELETE (IN EINOTEID INT)

LANGUAGE SQL

------------------------------------------------------------------------


------------------------------------------------------------------------

P1: BEGIN


DECLARE KeyVar INT;


DELETE FROM MRL_EMP_EIVD

WHERE EINOTEID = KeyVar;

END P1

Running Virtual Agents Against Virtual DocumentsChanges made to Virtual Documents by running a Virtual Agent againstselected documents in a view will produce updates in the documentsimmediately. However, if the Virtual Agent is updating values containedwithin a View column, that view will not immediately reflect the changesmade to the documents. In order to see these changes, users will need torebuild their index using the Shift + F9 function.

If you are running a Virtual Agent against an open Virtual Document,changes can be viewed after the document has been closed and reopened.This is similar to the behavior expected when running a native DominoAgent against an open document.


Chapter 14 Virtual Agents Activity




• Virtual Agents

This chapter provides information about the Virtual Agents Activity.

Introduction to Virtual Agents ActivitiesA Virtual Agents Activity creates Domino Agents that run storedprocedures on the external system database. The Agents that it creates areadded to the Domino Agent menu. If the stored procedures requireparameters, you must create Domino documents that hold theseparameters, then you select the document or documents and run the agentsagainst them.

Virtual Agents Activities execute external stored procedures in two ways:

• Without parameters

• Against selected documents that provide parameter values

Procedures that do not accept parameters do not run against anydocuments, they are created and specified as agents that “Run on alldocuments in database.” Procedures that do accept parameters are createdas agents that “Run on selected documents,” and require that at least onedocument be selected. All documents selected for virtual agents are used asa source for input parameters for the agent, and the input parameters forthe external stored procedure are obtained from the correspondinglynamed fields in the target document.

For example, if three documents are selected, the external stored procedurewill be run three times, once for each document using input parametersobtained directly from the relevant document. For each document theVirtual Agents is run against, the items corresponding to the procedureparameters are retrieved from the document and provided as inputparameters for the procedure.

237

Stored procedures in an external system are defined by a name andoptional inputs and outputs. Input data is always provided as parameters,while output data can be returned either as output (or input/output)parameters or returned result sets. Agents in Domino do not directlysupport parameters, but the ability in Domino to run an agent against oneor more documents provides the equivalent functionality.

Note Use the output parameters of a Virtual Agent Activity to modify anon-virtualized Notes document or non-virtualized fields in a Notesdocument receiving output parameters.

Note If the database is already open, the Virtual Agent will not berefreshed.

Note After stopping the activity, the agents will no longer appear.However, if the database was open in the client, the Actions menu willcontinue to display the agents until the database is closed and reopen.

Stored Procedure ParametersIf the stored procedures that the agents run against require arguments, youmust create Domino documents that have fields that are named exactly asthe parameters in the external system stored procedure are named. Oncethese fields are set up and the appropriate values are stored in them (forinput parameters), the agents can be run.

Creating a Virtual Agents Activity Using the User AssistantYou can optionally enable the User Assistant to prompt you the through thecreation of a new Virtual Agents Activity. You can toggle the User Assistanton and off using the Help option in the Navigator panel of theAdministrator.

This section describes how to create a Virtual Agents Activity using theUser Assistant. For options not described in these steps, see the chaptersentitled “LEI Administrator” and “Introduction to LEI Activities.”



If you have not made any selections from the User Assistant, clicking theCancel button on this message box closes the activity form and returns youto the LEI Administrator. Once you have made one or more selections whileyou are in the User Assistant, clicking Cancel causes the User Assistant toshut down, but the activity document stays open, in edit mode, displayingthe choices you have made up to that point. You can then manuallycomplete the activity document or abandon it.

Note Any choices you make while using the User Assistant can bechanged later by opening the activity document in edit mode.

Chapter 14: Virtual Agents Activity 239

Step 2: Select the Domino Database to MonitorA list of Domino databases appears. Select the Domino database to monitor.

Note When the list is large, you can scroll down the list to find the Dominoapplication (nsf) you want to select. However, if the list is too large to becompletely accommodated by scrolling, an overflow message appears at thebottom of the list (<overflow…>) and a box appears under the list, whichyou use to type in the exact name of the table you want to use. For moreinformation on browsing and browsing requirements, see “Browsing” in thechapter entitled “LEI Administrator.”

Monitoring uses the Notes replication ID of the application database. AVirtual Agents activity does not distinguish between the databases thatshare the same replication ID. Databases have the same replication ID whenthey are replicas of each other and when one database is created using theoperating system to copy an existing database.


Step 3: Select the Lotus Connection for the External Data SourceSelect the Connection for external data source you want to monitor fromthose available in the Select Connection dialog box, shown below.

Note When the list is large, you can scroll down the list to find the tableyou want to select. However, if the list is too large to be completelyaccommodated by scrolling, an overflow message appears at the bottom ofthe list (<overflow…>) and a box appears under the list, which you use totype in the exact name of the table you want to use. For more informationon browsing and browsing requirements, see “Browsing” in the chapterentitled “LEI Administrator.”


Step 4: Select the OwnerWhen prompted, select the metadata owner.

Step 5: Name the Activity DocumentWhen prompted, enter a unique activity name and click OK.



Click OK. The Virtual Agents Activity document appears, showing yourselections. The numbered icons in the document correspond to the majorsteps the User Assistant uses to create the activity.

Step 6: Select Options and Event OptionsSelect the options and the event options you want in the “Options” and“Event Options” tabs in the document. See the section “Virtual Agents —Options” later in this chapter for more information.

Step 7: Select Scheduling OptionsSelect how you want to control the scheduling of the Virtual Agentsactivity. The options are Manual, AutoStart, and Custom. See the“Scheduling” section later in this chapter for more information.

Step 8: Save and Close the DocumentChoose File - Save to save this Virtual Agents activity definition. ChooseFile - Close to close the Virtual Agents Activity document and return to theactivity administrator.


Step 9: Process the Virtual Agents ActivityYou can process the activity using the Start and Stop buttons in the Actionbar of the Activities View or the Favorites (Folders) View. (When you select“Auto Start” in the Scheduling section of the activity document, the VirtualAgents activity is established each time that the server starts. See theScheduling section for more information.)

Click the Virtual Agents activity to select it and then click the Start button tobegin processing it.

To stop a Virtual Agents activity, select the Virtual Agents activity and clickthe Stop button.

Creating a Virtual Agents Activity without the User AssistantYou can optionally enable the User Assistant to prompt you the through the creation of a new Virtual Agents Activity. You can toggle the UserAssistant on and off using the Help option in the Navigator panel of theAdministrator. If you disable the User Assistant, a blank activity documentis displayed, which you can fill in to define the activity.

This section describes how to create a Virtual Agents Activity without usingthe User Assistant. For options not described in these steps, see the chaptersentitled “LEI Administrator” and “Introduction to LEI Activities.”

Step 1: Open the Activity DocumentClick the Add Activity icon. The Virtual Agents Activity Documentappears.


Step 3: Select the Domino Application to MonitorClick the down-arrow icon in the “Domino Application” section. A list ofdatabases appears. Select the database that you want to monitor.

Note When the list is large, you can scroll down the list to find the Dominoapplication (.nsf) you want to select. However, if the list is too large to becompletely accommodated by scrolling, an overflow message appears at thebottom of the list (<overflow…>) and a box appears under the list, whichyou use to type in the exact name of the table you want to use. For moreinformation on browsing and browsing requirements, see “Browsing” in thechapter entitled “LEI Administrator.”


Note Immediate or “real-time” monitoring uses the Notes replication ID ofthe application database. A Virtual Agents activity does not distinguishbetween the databases that share the same replication ID. Databases havethe same replication ID when they are replicas of each other and when onedatabase is created using the operating system to copy an existing database.


Note When the list is large, you can scroll down the list to find the tableyou want to select. However, if the list is too large to be completelyaccommodated by scrolling, an overflow message appears at the bottom ofthe list (<overflow…>) and a box appears under the list, which you use totype in the exact name of the table you want to use. For more informationon browsing and browsing requirements, see “Browsing” in the chapterentitled “LEI Administrator.”

Step 5: Select Options and Event OptionsSelect the options and the event options you want in the “Options” and“Event Options” tabs in the document. See the section “Virtual Agents —Options” later in this chapter for more information.

Step 6: Select Scheduling OptionsSelect how you want to control the scheduling of the Virtual Agentsactivity. The options are Manual, AutoStart, and Custom. See the“Scheduling” section later in this chapter for more information.

Step 7: Save and Close the DocumentChoose File - Save to save this Virtual Agents activity definition. ChooseFile - Close to close the Virtual Agents activity document and return to theVirtual Agents activity administrator.

Step 8: Process the Virtual Agents ActivityYou can process the activity using the Start and Stop buttons in the Actionbar of the Activities View or the Favorites View. (When you select “AutoStart” in the Scheduling section of the activity document, the Virtual Agentsactivity is established each time that the server starts. See the Schedulingsection for more information.)

Click the Virtual Agents activity to select it and then click the Start button tobegin processing it.


To stop a Virtual Agents activity, select the Virtual Agents activity and clickthe Stop button.

Virtual Agents Activity Document OptionsOnce you have specified a Domino database and the connection you wantto use, there are a number of options for you to consider in setting up aVirtual Agents activity.

In this section, the options are organized into two major groups:

• General Options


See the chapter entitled “Introduction to LEI Activities” for a description ofthe following sections that are common to all Activity documents:

• Activity Name

• Scheduling

• Category

• Comments

General Options in Virtual AgentsThe General Options section of the Virtual Agents activity document,illustrated below, presents options that can be applied to a Virtual Agentsactivity. Each of the General Options is described after the illustration.

Note Stored procedures in the external system must not have anyparameters if they are to be used as Virtual Agents.


Save Output Parameters: This option instructs the activity to savethe output parameters returned by a stored procedure to theselected documents. If the stored procedure also modifies data inthe external system, care should be taken to ensure that it doesnot modify fields that are mapped to a selected virtualized record.In this situation, saving the output parameters to that record myoverwrite the modifications made directly to the external system.

OutputParameters

Delete Agents on Shutdown: This option instructs the activity todelete its virtual agents at shutdown. Leaving this optiondeselected takes advantage of noteid reuse. When the activity isrestarted, a new Virtual Agent document will not be created if onealready exists with the same name. Instead, the noteid is reused,but the contents of the agent document are recreated to catchmodifications of the stored procedure in the external system.

ShutdownOptions

This option sets the maximum number of connections to theexternal database that can be opened to service concurrent userrequests simultaneously (that is, users creating, opening,updating, and deleting documents at the same time).

LEI opens one connection to the external data source when thefirst Notes application event occurs. If two or more events occursimultaneously, additional connections are made, up to themaximum number of connections specified by this option. Whenthe maximum number of connections is reached, subsequentevents are queued and occur when each preceding event isserviced.

Each connection lasts only as long as necessary to read from orwrite data to the external data source. While the connection ispersistent, the time required to service each event is minimal anddepends on the amount of data being read or written. Themaximum number of connections, therefore, does not need to bevery large in order to service multiple events. Lotus recommendsthat you set the maximum connections to 2 or 3, and if usersexperience significant delays, you can increase this number.

Max.Connections

LEI runs only the agents you select. Click the down arrow to opena dialog box where you can select from a list of agents or type inwild cards (use * or ? for pattern searches).

Agent PatternList

If you specify an external owner, the choice of stored proceduresis limited to those owned by this owner. Click the down arrow tobrowse the list of owners.

Note Specifies the owner of the external system. You cannotbrowse the Agent Pattern List unless an External Owner Name isspecified.

External OwnerName



Integrated Credentials in Virtual AgentsUser credentials for the external system are automatically looked up whenthe Integrated Credentials options is selected. The credentials are used toconnect to the external system.

Note The integrated credentials database is described in the Introductionto Activities chapter of this document. See the section entitled “IntegratedCredentials Database” for information about setting up and usingintegrated credentials.

Note Virtual Agents only use integrated credentials for agent execution.

Each of the Integrated Credentials Options is described in the tablefollowing the illustration.


Missing Credentials — Enables you to specify howmissing credential data should be processed.

Use Connector Credentials — If you select this optionand there is a credentials lookup failure, defaultcredentials in the activity can be used. If you do notselect this option, the operation can fail (this is thedefault behavior).

Credentials DB Filepath — Enter the name of thecredentials database to be used for storing Notes usernames and corresponding external systems credentials.The path is specified relative to the LEI directory (forexample leidir).

Note You must have created this database using thetemplate leicred.ntf. See "Setting Up and UsingIntegrated Credentials" in the Introduction to Activitieschapter of this document.

Lookup Credentials

Uses the user ID and password that is specified in theConnection Document you are using in this activity.

Use Lotus Connector forxyz Credentials

DescriptionIntegrated CredentialsOptions

Executing Virtual Agents from HTTP ClientThere are two ways to execute a Virtual Agent if you are using a HTTPclient; directly through a URL or by adding the agent to a Web object in theform as you design it.

Using a URLYou can execute it directly through a URL. For example, if your agent wascalled “Update_VA” and was on the server MyServer and used thenames.nsf database, the URL command would be:

http://myserver.mysite.com/names.nsf/Update_VA?OpenAgent

Using a Web Object in the Form DesignThe other way to use your virtual agent via HTTP client is to enter youragent within the WebQuerySave or WebQueryOpen object in Designingyour Form. For example:

@Command([ToolsRunMacro]; "<Your agent goes here>")

Each time a form is saved or opened from the Web your Virtual Agent willlaunch.


Running Virtual Agents Against Virtual DocumentsChanges made to Virtual Documents by running a Virtual Agent againstselected documents in a view will produce updates in the documentsimmediately. However, if the Virtual Agent is updating values containedwithin a View column, that view will not immediately reflect the changesmade to the documents. In order to see these changes, users will need torebuild their index using the Shift + F9 function.

If you are running a Virtual Agent against an open Virtual Document,changes can be viewed after the document has been closed and reopened.This is similar to the behavior expected when running a native DominoAgent against an open document.

Running Virtual Agents Against Virtual FieldsChanges made to Virtual Fields documents by running a Virtual Agent will produce updates in the specified documents immediately. However, if the Virtual Agent is updating values contained within a View column,that view will not reflect the changes made to the documents, and pressingShift + F9 will not refresh the view.

In order for Virtual Fields to be displayed within a view, you must haveselected “Leave all/selected Real Time fields in document” when buildingthe activity. This, in effect, makes native copies of the fields within thedocument. These fields will not be updated or reflect changes made in theexternal system until the Notes document is updated manually or by usinga formula or script.


Chapter 15 Replication Activity

This chapter provides information about the LEI Replication Activity.

Introduction to the Replication ActivityA Replication Activity synchronizes databases by updating one databasefrom the data in another.

There are two types of replication available within the Replication Activityform:

• Primary Key Replication

• Timestamp Replication

A condition can also be used in the Replication Activity document’s Condi-tional Clause field to further refine the result set to achieve an enhanced,selective replication. See the section “Types of Replication Activities” laterin this chapter for more information.

You can control how the Activity resolves conflicts, which in LEI terms aresimply instances where a data item in one database does not exactly matcha data item in another database.

When to Use the Replication ActivityThe Replication Activity is recommended for use when you want to doeither of the following tasks.

• Synchronize data in two databases

• Merge data from one data source into another data source

You can also use the Replication Activity in conjunction with a PollingActivity to refine when the Replication Activity occurs. For example, youcould poll a data source for a specific event, such as a data insertion, and ondetection of that event start the Replication Activity that replicates the newdata in another data source.

251

Types of Replication ActivitiesThere are two main types of replication activities — primary key andtimestamp.

Primary Key ReplicationLEI primary key replication replicates data based on a unique key commonto both connections that can be composed of one or more fields in themetadata. The function of the primary key is to determine if matchingrecords exist in both data sources and if an update to a record, the insertionof a new record, or the deletion of a record is required.

When replication occurs, records are replicated according to the followingdefault rules:

• If a record with matching key values exists in both connections, and thedata field values are identical, no action is taken.

• If a record with matching key values exists in both connections, and thedata field values are different, the Target record is updated.

• If a Source record contains key values that are not present in the Target,a new record is inserted into the Target.

• If a Target record contains key values that are not present in the Source,that record is deleted from the Target.

Note In primary key replication, the Replication Activity never changesrecords in the Source connection.

Timestamp ReplicationYou can control replication based on timestamp fields provided in theActivity Document using the Enable Timestamp Replication option. Usingthis option requires that the two connections specified on the ActivityDocument (Source and Target) contain at least one timestamp field.

The Replication Activity Document maintains internal timestamp fieldsbased on the last replication from each respective connection. These fieldsare SrcTimeStamp and DestTimeStamp. You can see these fields by viewingthe document properties of the Activity Document. To do so, right-click


while active in the Activity Document or choose File - Document propertiesfrom the Notes top bar. Use the Fields tab and scroll down to locate thesefield names.

In timestamp replication, there is no designation of “source” and “target”.Replication actions can affect both connections. Because the connections aredesignated on the Activity Document as Source and Target, we use theseterms when explaining the following rules.

When replication occurs, records are replicated according to the followingdefault rules:

• If a Source record contains a timestamp value that is later than theSrcTimeStamp value, and a Target record does not exist with the samekey fields, a new record is inserted into the Target.

• If a Target record contains a timestamp value that is later than theDestTimeStamp value, and a Source record does not exist with the samekey fields, a new record is inserted into the Source.

• If a Source record contains a timestamp value that is later than theSrcTimeStamp value, and a Target record exists with the same keyfields, the Target record is updated.

• If a Target record contains a timestamp value that is later than theDestTimeStamp value, and a Source record exists with the same keyfields, the Source record is updated.

• Records are never deleted from either connection.

Note If a Source and Target record share the same key fields and containtimestamp values that are later than the SrcTimeStamp and theDestTimeStamp respectively, then the Target record is updated. In this case,the Replication Activity does not use the timestamp values to determine thereplication action.

Chapter 15: Replication Activity 253

Understanding How Timestamp Replication WorksThe first time that a timestamp replication occurs, all records in bothconnections are replicated according to the above rules because the initialvalues of SrcTimeStamp and DestTimeStamp are 01/01/0001 12:00:00 AM.Subsequent replications adhere to the rules already described with thefollowing consideration.

Replication action is determined using a timestamp window; not strictlybased on whether the record to be replicated has a timestamp value that isgreater than SrcTimeStamp or DestTimeStamp. In order for a source ortarget record to be replicated, its timestamp value must be greater than therespective internal timestamp value (SrcTimeStamp or DestTimeStamp) butmust also be less than the current system time of the database server.Consider the following example:

In the Replication Activity Document, the Source connection is DB2 and itsdesignated timestamp field is LASTUPDATED. The Source connectioncontains a record where LASTUPDATED is currently 03/27/02 11:31:46AM. The SrcTimeStamp field value is 03/27/02 10:47:07 AM. The currentsystem time of the DB2 server is 03/27/02 11:29:12 AM. This record will notreplicate. Although the 03/27/02 11:31:46 AM is greater than SrcTimeS-tamp (03/27/02 10:47:07 AM) it is not less than the current system time ofthe DB2 server (03/27/02 11:29:12 AM). You can avoid this situation byensuring that all your timestamps (especially those set with a trigger orformula) are in synch with one another.

Note The DB2 column used as the TIMESTAMP in timestamp replicationmust be of type TIMESTAMP, not DATE.

Using Timestamp Replication with Notes DatabasesDuring timestamp replication, the Replication Activity uses the Dominoserver time where the Notes database resides as the current system time todetermine if records should be replicated. It therefore becomes important touse a timestamp field that captures this time. Using @Modified retrieves themodified date/time for that document which was set by its Domino serverwhen the document was saved.

@Modified comes from the server. @Now comes from the desktop. Becausethe Domino server time and the Notes client workstation may not be inexact agreement about what time it is, it is probable that you will miss somedocuments during timestamp replication if the time on the client is earlierthan the time on the server. Therefore you must use @Modified to obtainthe proper time in any field formulas which will be used for timestamps.However @Modified is always one edit behind because the modified times-tamp is the last thing to be set when the document is saved. @Modifiedreads the modification time, but because the document contains the last


time the document was saved at the time the formula is executed, it will notreturn the time from the current save.

There are two options for solving this problem, as shown below:

• The first is to use the Notes Connection Option “Load last modifiedTimeStamp (@Modified).” In this case, @Modified would be enteredinto the timestamp field in the Replication Activity Form. This methodrequires no special changes to the Notes application. This option isdiscussed in more detail in the chapter on Notes connections.

• The second option involves modifying your Notes form to add aQueryClose event.

In your timestamp field (which should be a computed field), use thefollowing formula (where “EditedDate” is the fieldname of the fieldused for timestamp):

@IF(@IsDocBeingSaved;@Modified; EditedDate)

This formula places the modification timestamp from the Dominoserver into the field “EditedDate” if the document is saved, otherwise itdoesn’t change.

To have the field contain the real modified date, not the one from theprevious edit, create a QueryClose event script for the form. This eventwill perform two saves of the document. The first will set theEditedDate field to the modified time of the last edit. The second savewill set the modified time to the time of the save just performed. It ispossible to get to within a tenth of a second of the real time.

Sub Queryclose(Source As Notesuidocument, Continue AsVariant)


Dim doc As NotesUIDocument

Set doc = workspace.currentdocument

If doc.editmode Then

Call doc.save

Call doc.save

Else

Stop

End If

End Sub


Using Database Triggers with Timestamp ReplicationDatabase applications often use triggers to set timestamps when a row ofdata has been modified. When LEI replication updates a row, the triggermay reset the timestamp to the time modified in that file or database. Thismay cause unnecessary replications of this row back to the other databasethe next time replication is run. The trigger should be designed to detectwhether the client application or LEI is updating the row and should handlethe timestamp accordingly.

Specifying a Selection View in a Notes DatabaseTimestamp replication creates a temporary view based on the selectioncriteria of documents to be replicated. The Notes Connection Options field“View to Use for Selection” lets you specify a permanent view to be used toselect the documents that the Activity will use. Supplying a permanentview name can dramatically improve performance by not requiring thedatabase to be re-indexed every time the Activity runs. LEI requires theability to modify this view, so it should not be a view that users also access.

Sort Order ConsiderationsReplication produces result sets from both connections and scans the resultset a single time for corresponding keys. If the connections use different sortorders, then replication may pass over keys that are out of order thusproducing unnecessary inserts or deletes. To avoid this, the Order Metacon-nector is available to impose a consistent sort order on result sets. TheOrder Metaconnector should be used when the following conditions aremet, in which case it must be used for both connections:

• One or more keys are text. Sort order is not a problem for non-text keys.

• The connections in the replication sort differently. This varies byConnector. Some may use the same sort order even though theyconnect to different systems.

• The text keys contain characters that are included in those which sortdifferently. For example, Lotus Notes and Oracle may sort certainpunctuation characters differently, but if the text keys are purelyalphanumeric, the sort order differences may be irrelevant for thisreplication.

Note If the data being replicated is not on the same system and bothconnections use the same Connector (for example, DB2 to DB2 replication),the Order Metaconnector is not needed.

Note When data is obtained from an EBCDIC-based system, the sort orderwill differ from a non-EBCDIC system.


You should ensure that the sort orders specified for the databases used inthe replication are identical. One option for handling sort order differencesis to use a numeric key. You can also use the Order Metaconnector to gainfurther sort order control.

For issues arising from sorting differences based on case-insensitive stringcomparison, see the section entitled, “Field Mapping Options” later in thischapter.

How to Create a Replication ActivityThe Replication Activity Document defines information needed for a Repli-cation Activity. This information includes replication parameters andoptions for controlling data treatment.

The steps below outline the general procedure for creating a ReplicationActivity. See the other sections in this chapter for more information aboutthe particular fields and options on the Replication Activity Document.


2. Select Add Activity from the Administrator. Select Replication from theresultant list.

3. Fill in the required fields and select the desired options for the Activityin the Replication Activity Document.



There is a complete example of building a Replication Activity in the“Tutorials” appendix.


Replication Activity DocumentThe Replication Activity Document is shown below. To create a new Repli-cation Activity, click Add Activity and then select Replication from theresultant list. To open an existing Replication Activity, double-click its namein an Activities view.



Special SettingsThe Replication Activity has the following optional settings in the ActivityDocument action bar.

Clicking this button performs a standard replication; it clears thefields associated with Trial-Run Replication, effectively returningsome sections of the Replication Activity document to their defaultsettings. This deselects the Skip Conflicts option, deselects allConnection Restrictions, and sets the Source Connection as master.

To return to non-trial replications, select the Default Settings optionand click OK when prompted. The Default Settings option clears thesettings associated with Trial-Run Replication and restores theActivity to its default settings.

DefaultSettings

Trial-RunReplication

DescriptionButton


The Source and Target sections provide information on the data source anddestination. Connections must be created before they can be used in thisActivity Document.

SourceThe Source Connection fields are described below.

continued

Specifies the metadata, based on the type of connection chosen. Forexample, in a relational database the metadata is a Table; in a Notesdatabase the metadata is a Form.

MetadataType

Opens the selected Connection Document in Edit mode. EditConnection

Specifies the source database, by defined connection name, fromwhich data will be selected and copied.

The connection identifies the server and database with accessinformation. The Additional Information segment of the document(see below) identifies the metadata.

To display a list of available connections, click on the arrow to theright of the Source heading.

Connection

DescriptionField


Provides options that you can choose from to restrict the operationalbehavior of the Replication Activity relative to each connection. Foran extended example of how to work with restriction settings, see“Example Results for Restricted Settings” later in this chapter.

wwww Skip Insertions — Prevents any records in the Source connectionfrom receiving inserts during replication.

wwww Skip Updates — Prevents any records in the Source connectionfrom being updated during replication.

wwww Skip Deletions — Prevents any records in the Source connectionfrom being deleted during replication.

Enabling Skip Insertions, Skip Updates, and Skip Deletions causesreplication for that connection to not allow writeback modifications.This reduces the locking level, and may be used to avoid lockingone side of a replication when it is known that no changes will bemade to that side. This is especially useful when replicating fromnon-updateable views in a relational database.

Note These options are only available if you have selectedTimestamp Replication

SourceRestrictions

DescriptionField

TargetThe Target Connection fields are described below.

continued

Specifies the metadata, based on the type of connection chosen. Forexample, in a relational database the metadata is a Table; in a Notesdatabase the metadata is a Form.

MetadataType

Opens the selected Connection Document in Edit mode. This buttonis available only if you are in Edit mode.

EditConnection

Specifies the destination database, by defined connection name, towhich data will be copied.

To display a list of available connections, click on the arrow to theright of the Target heading.

Connection

DescriptionField


Provides options that restrict the operational behavior of theReplication Activity relative to each connection. For an example ofhow to work with restriction settings, see “Example Results forRestricted Settings” later in this chapter.

wwww Skip Insertions — Prevents any records in the Target connectionfrom receiving inserts during replication.

wwww Skip Updates — Prevents any records in the Target connectionfrom being updated during replication.

wwww Skip Deletions — Prevents any records in the Target connectionfrom being deleted during replication.

Enabling Skip Insertions, Skip Updates, and Skip Deletions preventsreplication, for that connection, from allowing writebackmodifications. This reduces the locking level and may be used toavoid locking one side of a replication when it is known that nochanges will be made to that side. This is useful when replicatingfrom non-updateable views in a relational database.

TargetRestrictions

DescriptionField

MappingThe Mapping section of the Activity Document enables you to specify eithermanual or automatic field mapping. The default is manual mapping. Bothmapping styles are described here.

For related information, see the Data Mapping section in the chapterentitled “Introduction to LEI Activities.”



Specifies the columns or fields used in the Targetconnection.

Target Column/Field(s)

Specifies the columns or fields used in the Sourceconnection.

Source Column/Fields(s)

Specifies a corresponding key field as that used for theSource Key(s) value.

Target Key(s)

Specifies the fields or columns of the data that togetherrepresent a unique primary key for that data collection.No two records can have the same value for all keyfields, and at least one key field is required. The keyfields for both connections must correspond. The SourceKey and Target Key value must match.

If using a Notes Connection as Source, see the“Metadata Creation: Select Target Metadata” descriptionfor the Data Options tab.

Source Key(s)

DescriptionField


Maps data from each source column to the destination by columnsequence: first column to first, second to second, and so on. To usethis option, the number of field names in the Source and Targetconnections must be identical or errors will occur. Positions mustbe identical; left to right or top to bottom.

By Position

Maps data from each source column to an identically namedcolumn in the destination metadata. To use this option, field namesin the Source and Target connections must be identical or errorswill occur.

By Name

Specifies the corresponding key field as that used for the SourceKey(s) value.

Target Key(s)

Specifies the fields or columns of the data that together represent aunique primary key for that data collection. No two records canhave the same value for all key fields, and at least one key field isrequired. The key fields for both connections must correspond. TheSource Key and Target Key value must match.

Source Key(s)

DescriptionField


Replication OptionsThere are several options available to you in the Replication Options sectionof the Replication Activity Document. Each subsection is described below.

Timestamp OptionsIf you select the Timestamp tab and then the Enable Timestamp Replicationoption, the following choices are available. As well, the three SourceRestrictions choices (Skip Insertions, Skip Updates, Skip Deletions) becomeavailable.


See “Source: Replicate TimestampField”.

Target: ReplicateTimestamp Field

See Source Timestamp definition.Target Timestamp

If you enable the Do Not Replicateoption, only the data field values, andnot the timestamp field value, arereplicated.

This prevents replication of records fromoccurring when the timestamp fieldvalue changes but the data field valuesdo not. The activity will not alter thetimestamp field; any change is left to thedata source to manage.

OptionalSource: ReplicateTimestamp Field

This specifies the name of the field thatholds the record’s timestamp value. If afield is entered here, the activitycompares both the timestamp and theprimary key. If used, a timestamp fieldname must be entered for both theSource and the Target.

Required forTimestampReplication

Source Timestamp

Selecting this option reinitializes thereplication timestamp of both metadatatimestamps (SrcTimeStamp andDestTimeStamp) to 01/01/0001 12:00:00AM.

This forces the next timestampreplication to behave as though noprevious replication has occurred and allrecords will be replicated. The option isuseful if replication has fallen out ofsync. For more information, see the rulesat the beginning of this chapter.

NoReset ReplicationTimestamp

Selecting this option enables timestampreplication. Primary key replication isthe default.

NoTimestamp Replication:Enable TimestampReplication

DescriptionRequiredField


Logging OptionsWhen you select the Logging Options tab, the following options appear,enabling you to log errors that occur during replication. This is helpfulwhen troubleshooting.

If enabled, this creates an entry in the activity logwhen an error occurs during replication. Theentry contains the keys from the record thatgenerated the error.

Log Key Values on Error

DescriptionField

Conflict OptionsThe Replication Activity Document provides options for specifying how toresolve conflicts that occur while the Activity runs.

The term conflict specifically refers to a data item in one database notexactly matching a data item in another database. A conflict occurs whenthe timestamp cannot resolve a “winner.” In keyed replication, all differ-ences are categorized as conflicts. In a timestamped Activity, only certaindiscrepancies are categorized as conflicts. Conflicts can be a normal eventduring replication. A decision must then be made as to how to resolve thisconflict.

In primary key replication, the Source connection is the one that wins anyreplication conflict.

Note You can optionally choose to log replication conflicts to a log file.These logged entries are not errors, but are rather instances of a conflictevent. Listing name conflicts to a log file helps you to both check theActivity and resolve any naming mismatches between the two databases.LEI allows you to control how replication conflict events are handled. Whenyou select the Conflict Options tab, the following options appear.


Used to limit logged conflicts to a useful number for the givenActivity. When this number of conflicts has been logged,additional conflicts are not added to the Activity log.

The default is 500. Specifying a value of zero indicates no limit(log all conflicts).

Limit To

Specifies how conflict logging will be performed.

wwww As Event — logs conflicts as errors in the Activity Logwwww As Error and Continue — logs conflicts as errors in the Activity

Log, but continues the Activitywwww As Error and Stop — logs conflicts as errors in the Activity Log

and stops the ActivityUsing the As Error options is slower, since each log entry iswritten to disk. Using the As Event options is much faster and isrecommended for production environments.

LoggingOptions

Logs conflicts in the Activity log. When you select Enable ConflictLogging, the form displays the Logging Options and Limit Tochoices described below.

Log Conflicts

Specifies that the conflict keys and data be saved to a specific tableor form (metadata) in either the Source or Target connection.

You must specify a table or form name using the browse andselect button to the right of the “Metadata Name” field name. Themetadata name that you specify receives the conflict loser records.

wwww Source — specifies that the metadata name is in the SourceConnection

wwww Target — specifies that the metadata name is in the TargetConnection

Conflict Link:MetadataName

Saves a document containing the conflict in the non-mastermetadata.

When you select the Save Conflict Data to Metadata, the formdisplays the Conflict Link: Metadata Name choices describedbelow.

ConflictHandling

DescriptionField


Data OptionsWhen you select the Data Options tab, the following options appear.

continued

When the option to create metadata is selected andmetadata creation is performed, an index will also becreated on the new metadata. The name entered is thename for the new index. The Replication Activity keyfields are the index columns.

Index creation may not be supported by all LotusConnectors.

An index is crucial for good performance against someconnections, such as relational databases.

Index to Create onMetadata Creation

When you select “Create Target Metadata”, the “Indexto Create on Metadata Creation” field appears.

Note When using a Notes connection as the SourceConnection and this option, the activity creates Targettext fields of 64996 bytes, the maximum size of a NotesText field. This causes legitimate errors with someRDBMS external systems during replication. To avoidthese errors, do not use a text field as a Source KeyField.

Metadata CreationCreate Target Metadata

DescriptionField


continued

Specifies how data is to be compared and how trailingspaces are to be processed.

Reduced-precision Comparison — Avoids falsemismatches as a result of differences between databasetypes in the precision used for storing datetime ortimestamp and floating point values. One database, forexample, may recognize fractions of seconds andanother not. This option uses a lower common degree ofprecision. Datetimes are compared to the second andwithout time zone or daylight savings time. Thisperforms date/time comparisons based on year, month,day, hour, minute, and second only. It also performsfloating-point comparisons to ten digits of precision.This option does not perform comparisons based ontime zones, daylight savings time, or hundredths of asecond.

This option is useful for replication between databasesthat do not support the same degree of date/timefloating point precision.

Case-insensitive String Comparison — This option isintended for use only when both connections in areplication use case-insensitive sorting (such as LEIreplication between two Notes connections). In thissituation, normal replication case-sensitive comparisonscan cause false conflicts.

Note Using this option causes replication to comparetext without case sensitivity.

Note This option does not cause the connections toperform case-insensitive sorting.

Disable Trimming of Text Trailing Spaces — Specifiesthat text fields that contain trailing spaces will not betrimmed.

Data Comparison andTrimming

DescriptionField


See the description for “Conditional Clause for Source”above and the following. As an example, if you have aSource and a Target table, each with 500 employeerecords with EmpID’s from 1-500, the following is true:

If your Conditional Clause for Target is set to EmpID >250, the Replication Activity will only use, forcomparison, records in the Target with EmpIDs greaterthan 250. Updates, inserts and deletes will then beperformed accordingly on the Target based on acomparison between the entire Source and records withEmpIDs greater than 250 in the Target.

Conditional Clause forTarget

Refines the Activity by including an optional conditionclause in the statement that is executed against theresult set based on key field(s). For example, a SQLWHERE clause or a Notes selection formula clause canbe used.

You can enter a condition for either or both connections.

The syntax of a conditional clause is defined by theconnection, however, it is not necessary to include anykeywords (such as SELECT or WHERE).

The conditional clauses act as filters for determiningwhich records are affected in both the Source andTarget. The clauses limit the records in the Source andTarget that are compared during a Replication Activity.As an example, if you have a Source and a Target table,each with 500 employee records with EmpIDs from1-500, the following is true:

If your Conditional Clause for Source is set to EmpID >250, the Replication Activity will only use, forcomparison, records in the Source with EmpIDs greaterthan 250. Updates, inserts and deletes will then beperformed accordingly on the Target based on acomparison between records with EmpIDs greater than250 in the Source and the entire Target.

Conditional Clause forSource

DescriptionField


Using the Do Not Replicate Timestamp OptionThe following table describes possible results when using the ReplicateTimestamp Field: Do Not Replicate settings found on the Timestamp tab onthe Replication Activity Document.

Update data field valuesonly in Source

Update Targettimestamp fieldvalue and datafield values

EnabledN/A

No actionUpdate Targettimestamp fieldvalue only

EnabledN/A

Update data field valuesand timestamp fieldvalue in Source

Update Targettimestamp fieldvalue and datafield values

Not EnabledN/A

Update timestamp fieldvalue only in Source

Update Targettimestamp fieldvalue only

Not EnabledN/A

Update data field valuesand timestamp fieldvalue in Target

Update Sourcetimestamp fieldvalue and datafield values

N/ANot Enabled

Update timestamp fieldvalue only in Target

Update Sourcetimestamp fieldvalue only

N/ANot Enabled

Update data field valuesonly in Target

Update Sourcetimestamp fieldvalue and datafield values

N/AEnabled

No actionUpdate Sourcetimestamp fieldvalue only

N/AEnabled

Result of Replication onRecord

Action on RecordTarget ConnectionDo Not ReplicateSetting

Source Connection Do Not ReplicateSetting


If the connection is using a timestamp that is set by the external systemdatabase through a trigger or as a result of saving the document, the Activ-ity has no effect on that timestamp. It is set per the rules of the externalsystem database. As an example, when using the “Modified” time on aNotes document, selecting the “Load Last Modified Timestamp(@Modified)” Connection Option will force the Activity to use the Modifica-tion time on the Notes document. If the document is changed during areplication, Notes will update that modification time as the document issaved. When a user or data entry application outside of LEI enters new dataor changes record data in a database, the timestamp field value is updatedto reflect the access date and time at which the latest modification occurred.

You can control whether or not the Activity updates the timestamp field inthe Target connection by using the “Do Not Replicate” option on the Sourceconnection.

This example table shows results when both connections are Notes and areusing the “Load Last Modified Timestamp (@Modified)” Connector Option.

continued

Update timestamp fieldvalue in Target (Targetis now later than Source)

Change Sourcetimestamp fieldvalue only

N/ANot Enabled


Change Targettimestamp fieldvalue and datafield values

Not EnabledN/A

Update timestamp fieldvalue only in Source

Change Targettimestamp fieldvalue only

Not EnabledN/A

Update data field valuesonly in Target,timestamp field valueset to time of documentchange (Target is nowlater than Source byNotes when documentwas modified).

Change Sourcetimestamp fieldvalue and datafield values

N/AEnabled

Does not updatetimestamp field value inTarget

Change Sourcetimestamp fieldvalue only

N/AEnabled



Source ConnectionDo Not ReplicateSetting


Does not update TargetChange Sourcetimestamp fieldvalue only

N/AEnabled

Does not update SourceChange Targettimestamp fieldvalue only

EnabledN/A

Update data field valuesand timestamp fieldvalue in Target

Change Sourcedata field valuesand timestampfield value

N/ANot Enabled


Change Targetdata field valuesand timestampfield value

Not EnabledN/A


Change Targettimestamp fieldvalue and datafield values

Not EnabledN/A

Does not update SourceChange Targettimestamp fieldvalue only

EnabledN/A

Update timestamp fieldvalue and data fieldvalues in Target

Change Sourcetimestamp fieldvalue and datafield values

N/ANot Enabled



Source ConnectionDo Not ReplicateSetting


Using Restrictions in Keyed Replication ActivitiesSettings for replication restrictions apply to the connection for which theyare set. For example, when options are set on the Target connection,changes to the Source will not affect the Target for the specified action.When the Trial Run Replication option is used, all replication restrictionsare ignored.

In keyed replication, the Target connection can benefit from restrictionsettings, but not the Source.

The following tables represent the effect of setting various replicationrestrictions on the target connection. The action performed when eachoption is set will produce the specified results to the data in the connectionfor which the option is set. The type of replication also determines behaviorof the destination. Keyed replications behave differently than timestampreplications. All of these options are used to manipulate the data transfer ina way that will cause the data to be different on each side of the replication.

Replaces with SourceDeletes from Target

Retains in TargetDeletes from SourceSkip Deletions

Does not update TargetUpdates Target

Does not update TargetUpdates SourceSkip Updates

Deletes from TargetInserts into Target

Does not insert into TargetInserts into SourceSkip Insertions

ResultActionTarget ConnectionSettings


Using Restrictions in Timestamp ReplicationSince timestamp replication is bi-directional (Source updates Target andTarget updates Source), it is possible to set restrictions for either connection.“Skip Deletions” is required on both Source and Target connections for alltimestamp replications, since deletions are never propagated to the otherconnection. It is assumed in this chart that Skip Deletions is set and alldeletions are ignored by each connection.

This table shows the Source Connection Settings.

Does not update SourceUpdates Target

Does not insert into SourceInserts into Target

Updates TargetUpdates Source

Inserts into TargetInserts into SourceSkip Inserts, Updatesand Deletions

Does not update SourceUpdates Target

Inserts into SourceInserts into Target


Inserts into TargetInserts into SourceSkip Updates andDeletions

Updates SourceUpdates Target

Does not insert into SourceInserts into Target


Inserts into TargetInserts into SourceSkip Insertions andDeletions

ResultActionSource ConnectionSettings


This table shows the Target Connection Settings.



Does not update TargetUpdates Source

Does not insert into TargetInserts into SourceSkip Inserts, Updatesand Deletions



Does not update TargetUpdates Source

Inserts into Target Inserts into SourceSkip Updates andDeletions


Inserts in SourceInserts in Target


Does not insert into TargetInserts into SourceSkip Insertions andDeletions

ResultActionTarget ConnectionSettings


Replication ExamplesThis section provides some examples that employ the Replication Activitywith replication restrictions.

Skip InsertionsIn this example, “Skip Insertions” is set on the Target and a record isinserted into the Source. The insertion is ignored by the Target in the nextreplication.

Use this option to prevent new records from being inserted into the Target.


Skip UpdatesIn this example, “Skip Updates” is set. A record is updated in the Sourcebut is not replicated into the Target.

Use this option to retain original data.


Skip DeletionsThe example below shows the effect of “Skip Deletions.” The Source hasdeleted a record but the deletion is skipped in the Target.

Use this option to preserve data in the Target that has been deleted from theSource.


Chapter 16 Java Activity

This chapter provides information about the LEI Java Activity.

Introduction to the Java ActivityA Java Activity allows LEI to launch a Java application.

When to Use the Java ActivityUse the Java Activity when you want to use LEI to launch a Java application.The Java application need not be restricted to LEI-specific applications. Aprogrammer can choose any IDE to develop and deploy applications.

When developing a Java Activity or Activity Document, consider thefollowing:

• The application must exist on the same machine as the LEI server that isdesignated to run that application.

• A Java JVM must also exist on that machine.

A Java Activity is useful in the following situations:

• When you need more elaborate control of source and destinationduring data transfers

• When you expect to perform different kinds of data massaging basedon certain application-specific conditions

Note The CLASSPATH variable on the machine that is running the JavaActivity must point to the class referenced in the activity. The system pathmust reference the location of the JVM used for the activity.

How to Create a Java ActivityThe steps below outline the general procedure for creating a Java Activity.See the other sections in this chapter for more information about theparticular fields and options on the Java Activity Document.

279


2. Select Add Activity from the Administrator. Select Java from theresulting list.

3. Enter the required class field and select the desired options for theactivity in the Java Activity Document.


Java Activity DocumentThe Java Activity Document specifies the information required to run anLEI Java application.

The Java Activity Document is shown below. To create a new Java Activity,click Add Activity and then select Java from the resultant list. To open anexisting Java Activity, simply double-click its name in the Activities view.


Note See the chapter entitled “Introduction to LEI Activities” fordescriptions of Activity Execution, Scheduling, and Other options.


JavaUse this section of the Java Activity document to identify the main JavaClass and optionally the CLASSPATH and Virtual Machine that the Activ-ity will use.

Specifies an optional Java Virtual Machine (JVM) override. Ifleft blank, java.exe will execute.

You may enter the path to an alternate JVM to execute theJava application. Doing so may require a change in theCLASSPATH.

Java VM (optional)

Optionally prepends the existing CLASSPATH environmentvariable set on the server that will execute the Javaapplication.

Class Path(optional)

Specifies the name of the Java Class to execute using anycommand line parameters. The class specified in the ClassName field should be in the CLASSPATH environmentvariable.

Class Name

DescriptionField

Chapter 16: Java Activity 281

Chapter 17 Scripted Activity

This chapter provides information about the LEI Scripted Activity.

Introduction to the Scripted ActivityA Scripted Activity is one that executes LotusScript (LSX) commands. LEIextends the LSX classes with additional methods to support the LEI Admin-istrator and log databases. Using LotusScript classes allows you extend thefunctionality available from the other LEI Administrator Activity operationssuch as Direct Transfer, Polling, and Replication.

You can use the LSX and a Scripted Activity to construct customizedroutines in situations where you need more complete control over sourceand destination data transfers. You can also use a Scripted Activity toperform data manipulation or evaluation during transfer.

Follow these steps to create a Scripted Activity.

Note The “Tutorials” appendix contains two excellent examples ofcreating a Scripted Activity. The first example illustrates how to use the twoagents supplied in the LEI Script Vault (leivlt6.nsf) database in conjunctionwith the supplied leipackagetrack.nsf sample database.

1. Install the Notes client or Domino Designer client to access the LC LSXclasses.

2. From the Lotus Notes or Domino Designer database Design Agentseditor window (also known as the Integrated DevelopmentEnvironment or IDE) type the following in the options section of thescript window.

Uselsx "*lsxlc"

3. Within the IDE, create the LotusScript routine using LC LSX classes.

Note Once you save the script and run it once, the system loads theLSX and the descriptions. The LC LSX classes appear automatically inthe Domino Classes section of the script browser drop down list.

283

4. In the Agent Properties box, set the Runtime target to None(@commands may be used in this type of agent).

5. Within the LEI Administrator — Scripted Activity, identify the LotusNotes database and server where the LotusScript routine has beenstored. Proceed to schedule and execute the LEI Scripted Activity.

See the Lotus Connectors LotusScript Extensions Guide for more informationabout the LSX.

Script development requires that either a Notes client, Designer Client,and/or the LEI server be installed. In the Lotus Notes or Designer client,you can edit, compile, and test LC LSX scripts, with or without namedsessions which requires LEI functions. However, only LC LSX scriptswithout named sessions can be deployed on the Notes client, since LEIfunctions are designed to be used for batch jobs. Scripts with namedsessions are deployed as Scripted Activities. With LEI installed, scripts mustread their connection information from the LEI Administrator.

Use of the LEI Administrator and logging is established when the LCSes-sion class object is created. Scripted Activities require that the first LotusConnector class object created be an LCSession object. The LCSession objectmust be created with a name.

Note With Scripted Activities, the activity name is used in the log. Thesession name is only used in the log when the Activity is run manually (notas part of a Scripted Activity).

Use of the LEI Administrator changes the behavior of the LCConnectionclass. LEI requires that the name given when creating each LCConnectionobject be the name of an existing Connection Document. The connectionparameters are loaded from the corresponding Connection Document. Bycontrast, the LSX requires that the name given when creating each LCCon-nection object be the Connector’s library name and all parameters must beassigned explicitly.

When a scripted agent is called, it is calling a defined activity. This activitymust have named Connection Documents associated with it. As a result,when the LCConnection object is instantiated with the following call, the<libraryname> takes on a new meaning within this context. It becomes thename of a connection to be used by the script.

Dim <connectionname> as New LCConnection ( <libraryname> )


How LEI Supports LotusScriptThe LEI LotusScript is first created as an agent using the Notes IntegratedDevelopment Environment (IDE), and later LEI executes the agent. The LCLSX extends the LotusScript language to support the complete LEIprogramming interface. Script development requires that either a Notesclient, Designer client and/or the LEI server be installed.

Note In the Lotus Notes or Designer client, you can edit, compile, and testLC LSX scripts, with or without named sessions which requires LEIfunctions. However, only LC LSX scripts without named sessions can bedeployed on the Notes client, since LEI functions are designed to be usedfor batch jobs. Scripts with named sessions are deployed as ScriptedActivities.

When editing a LotusScript agent, the Notes IDE loads the LC LSX. Thispermits the LotusScript syntax to be verified. When the agent is executed ordebugged, the LSX establishes a connection with the local LEI server orclient to process database connections and perform logging.

To use the LEI extensions to LotusScript, include the LC LSX within ascripted agent.

Both the Notes and LEI program directories must be listed in the systempath. Notes requires the LEI program directory to be in the path so the IDEcan load the LSX for authoring and testing of the agent. LEI requires theNotes program directory to be in the system path so that the agent may beexecuted as part of the Scripted Activity.

See Appendix E of the Lotus Connectors LotusScript Extensions Guide fordetails on LEI-specific behaviors, including descriptions of the LCSessionand LCConnection classes. See the previous section entitled “How to Createa Scripted Activity.” Also see the examples in the “Tutorials” appendix ofthis manual.

Running Unrestricted LotusScript AgentsTo execute unrestricted LotusScript agents you must grant permission to“*“. In addition, either “Default” or (more secure) the signer of the agentmust have Editor access to the LEI Administrator database with permissionto delete documents.

Chapter 17: Scripted Activity 285

How to Create a Scripted ActivityThe steps below outline the general procedure for creating a Scripted Activ-ity. See the other sections in this chapter for more information about theparticular fields and options on the Scripted Activity Document.


2. Select Add Activity from the Administrator. Select Scripted from theresulting list.

3. Fill in the required fields and select the desired options for the Activityin the Scripted Activity Document.

Note All connections referenced in the activity should exist and bevalid. To test the validity of a connection, use CONTEST as described inthe Lotus Connectors and Connectivity Guide.


There are two examples of building a Scripted Activity in the Tutorialsappendix.

Scripted Activity DocumentThe Scripted Activity document includes the name of the Notes agent thatcontains the LSX script to be executed, as well as the standard schedulingoptions common to all Activities.

To view the agent, select the Notes database which contains the agent (thedefault is the LEI Script Vault). Next, choose View - Design from the topmenu and then select Agents in the Navigator.


The Scripted Activity Document is shown below. To create a new ScriptedActivity, click Add Activity and then select Scripted from the resultant list.To open an existing Scripted Activity, simply double-click its name in theActivities view.



ScriptThis section identifies the LotusScript that the activity will use.

Specifies the name of the agent containing the script to execute.Punctuation, leading or trailing spaces and so on are not acceptableagent name characters.

The Agent button located next to the field displays the list ofagents available for the selected database.

Agent Name

Specifies the Notes database file path and name where the agentcontaining the script is found.

The Agent Database browse button located next to the fielddisplays the list of databases available on the server chosen above.The LEI Script Vault database installed by LEI is leivlt6.nsf.

AgentDatabase

Specifies the server where the agent containing the script islocated.

Agent Server

DescriptionField

See the chapter entitled “Introduction to LEI Activities” for descriptions ofActivity Execution, Scheduling, and Other options.

Agent Development DocumentYou can use the Agent Development document to create a LotusScriptagent. You can also use it to perform one of the following actions — simple,formula, LotusScript, imported Java, or Java.

1. To open the Agent Development document, click the Create Agentbutton in the Scripted Activity Document.

If prompted, specify the server name and database name (if you haveremoved the entries from the Activity Document). The default namesare those specified in the Agent Server and Agent Database fields of theActivity document.

2. The specified database (for example the LEI Script Vault databaseleivlt6.nsf) is opened in Domino Designer. Select the Create Agentbutton in this view.


This database is most easily specified using the Agent Server and AgentDatabase options on the Scripted Activity Document.

3. Enter a name for your new agent and any other dialog box options thatare applicable to you. Click the X in the top right of the dialog box tocontinue.

This name can then be used in the Agent Name option on the ScriptedActivity Document.


4. Create your agent syntax in the resultant Agents view. Please see theNotes Help system to specific details about how to perform this task.

For more information about creating an agent, see the Notes onlinedocumentation.

Determining if an Agent is RunningTo check to see if an agent is running, type the following Show Taskcommand in the Domino server console:

sh ta

One of the processes listed will be the Agent Manager. It will display aseither idle or as the name of the task that it is running. To check the log afterthe script has run, open the database that it is stored in, select the agent, andfrom the top menu choose Agent - Log.

The log is overwritten each time the agent runs. For each run, the log willstate the number of documents selected and the time it started and stopped.


Scripted Activity ConsiderationsThis section contains several suggestions for writing Notes agents to beused in LEI Scripted Activities.

• The LEI and Notes directories must be listed in your path forLotusScript to execute correctly.

• When creating agents, select Shared and specify None as the Targetvalue on the Agents menu.

• Provide support for both LEI errors and LotusScript errors.

• To test agents using the Notes Integrated Development Environment(IDE), choose “Debug LotusScript” from the File - Tools menu and thenrun the agent from the menu. You will need either an LEI server, Notesclient, or Designer client installation on the local machine.

In addition, Notes password entry is not permitted. Either a Notes IDwithout a password must be used or the option “Share password withNotes add-ins.” Choose the Notes menu option File - Tools - User ID.


• You can organize your agents within the LEI Script Vault database(leivlt6.nsf), the Notes databases where related data resides, or in someother database.

Note Since these agents are “shared,” they will be deleted if thedatabase design is replaced or refreshed. You should disable the designinheritance of the Notes database where you choose to store the agents.

• A Scripted Activity cannot open a database that is on a remote iSeriesor UNIX server.


Appendix A LEI and Data

This appendix provides information about LEI data types and datamapping.

Notes and Relational DatabasesLEI can pass data between data sources, including Notes. It can be helpfulin these cases to understand the match-up between Notes objects anddatabase objects. The metadata object of an LEI Activity is a table in arelational database or a Notes form. The following table summarizes LEIterminology in relation to Notes terms and traditional relational databasevocabulary.

Selection formulaSQL queryStatement

Document or RowRowRecord

Field or ColumnColumnField

Form or ViewTable, View, Stored ProcedureMetadata

Database (.nsf file)DatabaseDatabase

Notes TermRelational DB TermLEI Term

LEI Data TypesLEI uses the following data types internally when transferring and manipu-lating data. LEI converts original data types to the closest matching LEItype, retaining information about the original type. When appropriate, LEIcan then convert data back to its original type.

continued

8-byte floating point value,corresponding to a C double

DescriptionFLOAT

9 digitsPrecision

-2147483647.00Minimum value

2147483647.00Maximum value

4-byte signed integerDescriptionINT

ParametersData Type

293

4GBMaximum length

Fixed/variable length, case sensitivityProperties

BLOB (unformatted), Composite (NotesRich Text), Text List (multivalue Text),Number List (multivalue Number),Datetime List (multivalue Datetime),

Available formats

Binary stream with optional binaryformat information

DescriptionBINARY

4GBMaximum length

Fixed/variable length, case sensitivityProperties

character-set specific text streamDescriptionTEXT

0.01 seconds Accuracy

1/1/1Minimum value

12/31/32767Maximum value

8-byte datetime value with timezoneDescriptionDATETIME

-127.00Minimum scale

127.00Maximum scale

88 digitsMaximum precision

0.00Minimum positivevalue

9.99…99e126Maximum positivevalue

High-precision packed numeric value DescriptionNUMERIC

4.00Scale

19 digitsPrecision

-922337203685478.00Minimum value

922337203685478.00Maximum value

8-byte signed integer value: four fixeddecimal places

DescriptionCURRENCY

15 digitsPrecision

0.00Minimum positivevalue

1.7976931348623158e+308Maximum positivevalue

ParametersData Type


The Meaning of NULLLEI regards a NULL as an undefined value, one that cannot be compared toother values. It is not equivalent to an empty string or to an empty valuesuch as zero. A replication will occur, for example, if LEI finds a NULL in adatabase matching an empty value in the replica. In such cases, use SQLsyntax to convert NULLs to values that are equivalent across databases.

LEI evaluates the absence of a field in a Notes database as a NULL.

Year 2000 SolutionLEI uses the Pivot Date solution to the year 2000 date problem.

How LEI interprets two-digit dates is dependent on the Century boundarysetting in the notes.ini file. The EICenturyBoundary variable can be set toany number between 0-101.

If the year is less than the boundary number, then the century 2000 will beused. If greater than or equal to the boundary, the century is 1900. If theboundary number is 101, then LEI uses the current century. The defaultboundary is 50. Zero always means 1900 and 100 always means 2000.

Examples are shown below.

99 = 209955 = 205500 = 2000EICenturyBoundary = 100



99 = 199955 = 195500 = 1900 EICenturyBoundary = 0

How 2-digit years are translated

Appendix A: LEI and Data 295

Appendix B Error Messages and Troubleshooting

This appendix provides information for troubleshooting LEI.

Installation TroubleshootingSee the IBM Lotus Enterprise Integrator for Domino (LEI) Installation Guide forinformation about troubleshooting the LEI installation.

For more information, see the following Web site:


Basic LC LSX ErrorsLCFAIL_MEMORY: Unable to allocate memory.

A memory allocation request failed. Either reduce memory requirements orfree up system resources. Common causes for this error include extremelylarge fieldlist record count or fixed stream length.

LCFAIL_UNAVAILABLE: Requested functionality is not available.

A request cannot be satisfied. This is most commonly returned from aconnection which does not support a particular function or operation, forexample a read-only connection would return this in response to an Insertoperation.

LCFAIL_END_OF_DATA: The last data value has been retrieved.

This indicates the normal end of processing from any iterative operation,and should not normally be treated as an error condition. All iterativeoperations, such as fetching from a result set or listing fields, will eventuallyreturn this status code indicating that there are no more results available.

LCFAIL_INVALID_INDEX: Cannot locate list element.

An index parameter provided is beyond the range of the object. Forexample, requesting the third record from a two-record fieldlist wouldreturn this error.

297

LCFAIL_INVALID_LIST: Invalid list direction.

An LCLIST enumeration parameter was not valid. One of the LCLIST_XXXconstants must be provided for any list parameter.

LCFAIL_INVALID_CONVERT: Invalid conversion.

Conversion is not supported between the source and target types. Forexample, conversion between numbers and datetimes will result in thiserror.

LCFAIL_INVALID_TEXT_LIST: This operation requires a valid text list.

An LCTextList function requires LCThisTextList to be a stream with a validtext list format (format LCSTREAMFMT_TEXT_LIST and a length of atleast two) or a single text value (type LEITYPE_TEXT). Either one of theseconditions was not satisfied or the data was not a valid text list.

LCFAIL_INVALID_NUMBER_LIST: This operation requires a validnumber list.

An LCNumberList function requires LCThisNumberList to be a streamwith a valid number list format (format LCSTREAMFMT_NUMBER_LISTand a length of at least four). One of these conditions was not satisfied orthe data was not a valid number list.

LCFAIL_INVALID_DATETIME_LIST: This operation requires a validdatetime list.

An LCDatetimeList function requires LCThisDatetimeList to be a streamwith a valid datetime list format (formatLCSTREAMFMT_DATETIME_LIST and a length of at least 4). One of theseconditions was not satisfied or the data was not a valid datetime list.

LCFAIL_ZERO_INDEX: All index values are one or greater – an index ofzero is not valid.

An index parameter provided is zero and all index values for LEI objectsare one or greater.

LCFAIL_ZERO_COUNT: This operation requires a non-zero count.

A count parameter provided is zero, which is not valid in the currentcontext. Most count parameters must be one or greater.

LCFAIL_ZERO_OFFSET: All offset values are one-based – an offset of zerois not valid.

An offset parameter provided is zero, and all offset values for LEI objectsare one or greater.


LCFAIL_ZERO_FORMAT: This operation requires a non-zero streamformat.

A stream format parameter provided is zero, which is not valid in thecurrent context. Most, but not all, stream format parameters must be a validLCSTREAMFMT_XXX constant.

LCFAIL_NULL_BUFFER: A NULL buffer was provided when one wasrequired.

A NULL pointer was provided for a memory buffer parameter, which is notvalid in the current context. Some buffer parameters (usually input buffers)must be valid pointers.

LCFAIL_NULL_RESULT: A return parameter is required, but none wasprovided.

A NULL pointer was provided for an output parameter. Some outputparameters, such as created objects, require valid pointers.

LCFAIL_FIXED_LENGTH: A fixed-length stream requires a non-zerolength.

An LCSTREAM object with the flag LCSTREAMF_FIXED allocates a fixed-length buffer at stream creation time. The length is determined by thestream’s maximum length property, which cannot be zero for a fixed-lengthstream.

LCFAIL_INVALID_FLAGS: The supplied flags are invalid, possibly due toa conflict.

A flags parameter contains invalid or conflicting flags. A few flagsconstants cannot be used together (for example, LCFIELDF_KEY_GT andLCFIELDF_KEY_LT).

LCFAIL_TEXT_TRANSLATE: Text translation failure.

Translation between text stream formats failed.

LCFAIL_NULL_FIELDNAME: A NULL field name was provided.

A NULL pointer was provided for a field name parameter. A valid pointeris required.

LCFAIL_INVALID_FIELDLIST: Invalid fieldlist.

An invalid LCFIELDLIST object instance/handle was used.

LCFAIL_INVALID_CONNECT: Invalid connect.

An invalid LCCONNECT object instance/handle was used.

Appendix B: Error Messages and Troubleshooting 299

LCFAIL_EMPTY_FIELDLIST: This operation cannot be performed on afieldlist with no fields.

A fieldlist with no fields was used in an operation that is invalid on anempty fieldlist. Add one or more fields to the fieldlist and retry theoperation.

LCFAIL_NAME_FIELDLIST: This operation cannot be performed on aname-only fieldlist.

A fieldlist allocated with a record count of zero contains field names onlyand no field data. Such a fieldlist cannot be used in the current context. Usea fieldlist allocated with a record count of one or greater.

LCFAIL_FIELDLIST_REF: Cannot alter fields in a multiply-referencedfieldlist.

A fieldlist created as a reference copy of another fieldlist shares field dataspace with the original fieldlist. Fields cannot be added to or removed fromsuch a fieldlist as long as one copy still exists.

LCFAIL_RECORD_INDEX: An invalid fieldlist record index wasencountered.

An lcRecordIndex parameter was invalid for the corresponding fieldlist. Arecord index must be no greater than the number of fields in the fieldlist.

LCFAIL_RECORD_COUNT: Request to transfer more records thanallocated in fieldlist.

An lcRecordCount parameter was invalid for the corresponding fieldlist. Arecord count must be no greater than the number of fields in the fieldlist,less the record index.

LCFAIL_LIST_SETUP: Fieldlist iteration requires initial setup.

Iterating through fields in a fieldlist with LCFieldlistList requires thatLCFieldlistListSetup be called first to prepare the fieldlist for iteration.When LCFieldlistList is called before LCFieldlistListSetup for a particularfieldlist instance, this error is returned.

LCFAIL_NO_MERGE_DATA: The data fieldlist in a merge cannot be aname-only fieldlist.

A fieldlist allocated with a record count of zero contains field names onlyand no field data. Such a fieldlist cannot be used as the LCDataFieldlistparameter for an LCFieldlistMerge or LCFieldlistMergeVirtual operation.


LCFAIL_NO_RESULTSET: This operation requires an active result set.

The requested operation cannot be performed against a connection withoutan active result set. A result set must first be created in the connection withLCConnectExecute, LCConnectSelect, or LCConnectCatalog.

LCFAIL_NO_WRITEBACK: This operation requires an active writebackresult set.

The requested operation cannot be performed against a connection withoutan active writeback context. A writeback result set (WRITEBACK propertyset to TRUE) must first be created in the connection and a successful Fetchoperation performed before a writeback Update or Remove operation isvalid.

LCFAIL_WRITEBACK_COUNT: Writeback operation record counts mustbe one.

Writeback updates, and removes operate on the current record in a connec-tion’s result set. For these operations, the lcRecordCount parameter must beone.

LCFAIL_STATIC_PROPERTY: Static activity properties cannot be usedwith unnamed activities.

Activities initiated with LCActivityAlloc and no activity name exist outsidethe context of the LEI Administrator. Since static properties are storedwithin the activity document in the Administrator, they are not valid forunnamed activities.

LCFAIL_LCXINIT: LEI system has not been initialized.

The LEI API system must be initialized before calling any LEI functions.The system is initialized by command-line execution of an activity or callingLCActivityAlloc. This error is returned when LEI API functions are calledbefore the system is initialized.

LCFAIL_ACTIVITY_NOT_INIT: The activity must be initialized beforeperforming any operation.

The activity context must be initialized before calling any LCActivityfunctions. The activity context is initialized by command-line execution ofan activity or calling LCActivityAlloc. This error is returned when activityfunctions are called before the activity context is initialized.

LCFAIL_ACTRUN_TIMEOUT: Timeout while running synchronousactivities.

When executing synchronous activities via LCActivityRunActivity andusing a timeout, this error is returned if the timeout occurs before allsynchronous activities and their subordinate activities have completed.


LCFAIL_NOT_CONNECTED: This operation requires a connection to aConnector. This error is returned by LCConnect functions which require asuccessful call to LCConnectConnect. All functions which manipulate orretrieve data require a successful connection.

LCFAIL_CONNECTED: This operation cannot be performed with a validConnector connection.

This error is returned by Connectors which require a particular operation tobe performed before establishing a connection with LCConnectConnect.

LCFAIL_EXTERNAL: External error.

This error indicates that an error external to LEI has been produced. Thespecific external error code and error text are usually available to provideadditional information.

LCFAIL_ACTIVE_SUBCONNECTION

The subconnection (connection property) of a metaconnection can only beset once. This error occurs when setting the property, but a valid setting hasalready been made.

Basic LC LSX Events (Non-Error)LCEVENT_EXTERNAL: External event

This status code indicates that an event external to LEI has been produced.This is an informational message. The specific external event code andevent text are usually available to provide additional information.

Extended LC LSX ErrorsLCFAIL_INVALID_METADATA: Metadata object <metadata> does notexist.

The metadata object to use is provided in the METADATA property. Thecurrent value for this property does not represent a valid metadata object inthis connection.

LCFAIL_TYPE_MISMATCH: Type mismatch for field <fieldname>; LEI:<type>, Connector: <type>.

When matching LEI fields to connection fields, the basic type class mustmatch. They must both be numbers, datetimes, or streams. This error isreturned when there is a data type mismatch.

LCFAIL_DUPLICATE: Duplicate object <name>.

An attempt to create an object failed since an object of the same namealready exists.


LCFAIL_FIELD_COUNT_MISMATCH: Field count mismatch; LEI:<count>, Connector: <count>.

When mapping fields, mismatched fields are only valid in certain circum-stances. In general, if there are more source fields than target fields, thiserror is returned.

LCFAIL_KEY_COUNT_MISMATCH: Key count mismatch; LEI: <count>,Connector: <count>.

When using key fields, the same number of field names must be provided.

LCFAIL_STAMPFIELD_TYPE: Timestamp field <fieldname> must be typedatetime; Actual: <type>.

When providing a timestamp field, the field must be of a datetime-compatible data type.

LCFAIL_FIELD_TYPE: Type mismatch for field <fieldname>used in thiscontext; Expected: <type>, Actual: <type>.

Certain operations expect certain data types. This error is returned when afield is used for a particular purpose, but does not have the proper datatype.

LCFAIL_MERGE_FIELD: Field mapping failed due to a missing field<fieldname>.

When mapping fields, a valid match must exist for all required fields. If afield does not have a corresponding match, this error is returned.

LCFAIL_MISSING_PROPERTY: No value supplied for required property<property>.

A particular property must be set before the requested operation can beperformed. For example, the INDEX property must be provided beforeattempting to create an index.

LCFAIL_PROPERTY_CONFLICT: Conflicting values for properties<property> and <property>.

Values for two properties conflict. In some cases, properties are exclusive orinterrelated, and certain combinations are not allowed. See the relevantconnection or activity documentation for more information.

LCFAIL_INVALID_PROPERTY: Invalid property <property>.

A property not supported by the connection or activity was referenced.


LCFAIL_PROPERTY_VALUE: Invalid property value for property<property>.

A property value is not valid. See the relevant connection or activitydocumentation for more information.

LCFAIL_INVALID_CHARSET

The character set indicator is not a valid representation. Valid character setrepresentations are any LEI supported character set suffix, listed in the“Character Sets” appendix of the Lotus Connector LotusScript ExtensionsGuide. For example, for LCSTREAMFMT_IBMCP850, use IBMCP850.

LCFAIL_READ_ONLY_PROPERTY

An attempt was made to set a read-only property - the connection does notsupport assignment of the property, only access.

Extended LC LSX Events (Non-Error)LCEVENT_CHARACTER_SET: Unsupported connection character set<charset>; using native character set.

This status code indicates that a connection’s character set could not bematched to any available LEI character set. This is usually not an errorsituation, but rather an informational message. The local machine’s nativecharacter set will be used.

Extended LC LSX Fieldname ErrorsLCFAIL_OVERFLOW: Data overflow in field <fieldname>.

A data overflow occurred when transferring data to or from a field. Fornumbers, an overflow indicates a value with a magnitude too large. Fordatetimes, an overflow indicates a year beyond the supported range. Forstreams, an overflow indicates a value too long. To suppress an overflowerror, use the field flag LCFIELDF_TRUNC_DATA or the stream flagLCSTREAMF_TRUNCATE.

LCFAIL_PRECISION_LOSS: Data precision loss in field <fieldname>.

Precision loss was detected during type-checking. For efficiency, precisionloss is only checked during type-checking, To suppress a precision losserror, use the field flag LCFIELDF_TRUNC_PREC.

LCFAIL_INVALID_INT: Invalid integer value in field <fieldname>.

An invalid integer reference, value or text representation was encountered.

LCFAIL_INVALID_FLOAT: Invalid float value in field <fieldname>.

An invalid float reference, value or text representation was encountered.


LCFAIL_INVALID_CURRENCY: Invalid currency value in field<fieldname>.

An invalid currency reference, value or text representation wasencountered.

LCFAIL_INVALID_NUMERIC: Invalid numeric value in field<fieldname>.

An invalid numeric reference, value or text representation wasencountered.

LCFAIL_INVALID_DATETIME: Invalid datetime value in field<fieldname>.

An invalid datetime reference, value or text representation wasencountered.

LCFAIL_INVALID_STREAM: Invalid stream value in field <fieldname>.

An invalid stream reference or value was encountered.

LCFAIL_INVALID_FIELD: Invalid field <fieldname>.

An invalid LCFIELD object instance/handle was used.

LCFAIL_INVALID_TYPE: Invalid data type for field <fieldname>.

An invalid type constant was used. Only valid LEITYPE_XXX constantsmay be used to represent a data type.

LCFAIL_INVALID_KEY: Invalid key field <fieldname>.

A key field name provided does not correspond to a valid field. Key field-names must exist in the relevant metadata.

LCFAIL_DUPLICATE_KEY: Duplicate key field <fieldname>.

A key field name was used twice in the same key list. Remove the duplicatereference.

LCFAIL_INVALID_STAMPFIELD: Invalid timestamp field <fieldname>.

A timestamp field name provided does not correspond to a valid field.timestamp fieldnames must exist in the relevant metadata.

LCFAIL_INVALID_FIELDNAME: Field name <fieldname> is not valid inthis context.

A field name provided is not valid in the current context. In some cases,field names are restricted in their usage for a particular connection or activ-ity.


LCFAIL_VIRTUAL_FIELD: Unsupported virtual field <fieldname>.

A virtual field was found, but the field name is not valid for the connection.See the Connector documentation for a list of valid virtual fields for aparticular connection.

LCFAIL_VIRTUAL_VALUE: Invalid data value for virtual field<fieldname>.

Some virtual fields place restrictions on valid field values. See the Connec-tor documentation for additional information on virtual field values for aparticular connection.

LCFAIL_INVALID_ORDER: Invalid ordering field <fieldname>

An ordering field name provided does not correspond to a valid field.Ordering fieldnames must exist in the relevant metadata.

Other General LEI MessagesMonitor failure — Error: This operation requires an active result set,Connector Notes Method - SetProperty.

This message indicates that LEI is attempting to open a document createdas a Notes to Notes Advanced RealTime Activity. However, Notes to NotesAdvanced RealTime is not supported. Specifically, in a Notes AdvancedRealTime Activity a Notes database cannot be the external system database.

Cannot use a Notes connection to a local database — Error: No suchdatabase exists: The activity attempting to browse metadata in a connectionto a local database cannot locate that database. This occurs when the LEIAdministrator hosted by the LEI server does not reside on the Dominoserver.


Activity LogsThe activity log documents contain some hidden fields which may beuseful. The documentation of these fields is not meant to be a commitmentby Lotus software to keep this format consistent for the future, and thesefields may not be compatible with previous or future LEI versions.

Field “Error”: When an activity ends in an error state, this field contains anon-zero number that indicates the LEI error code representing the initialerror that placed the activity into an error state. When this field is zero ornot present, the activity ended in a non-error state (either successfully, orwith all errors explicitly cleared).

Field “CountList”: This is a list of numbers that indicate the counts of inter-nal connector function calls and record transfers. The entries in this numberlist are as follows:

Number of calls to Connect

Number of calls to Disconnect

Number of calls to Execute

Number of calls to Select

Number of calls to Fetch

Number of calls to Insert

Number of calls to Update

Number of calls to Remove

Number of calls to Action

Number of calls to Catalog

Number of calls to Create

Number of calls to Drop

*Number of records returned through Execute

*Number of records returned through Select

*Number of records Fetched

*Number of records Inserted

*Number of records Updated

*Number of records Removed

*Number of records returned through Catalog

* — Indicates that when the number count cannot be determined, the value4294967295 will be used instead, meaning indeterminate.


Troubleshooting LEI on iSeriesThis section addresses some common problems of using LEI on iSeries.

Below are some common error messages and solutions you may encounterwhen running an LEI activity.

continued

If going to a remote DB2/400 datasource, make sure the password isUPPER case. If going to any otherDB2 data source, make sure thepassword reflects the case sensitivityrequired on that target platform.

This message is mostlikely because thesupplied user name isnot correct or theprovided password isnot correct. Note thatthe password for datasources can be casesensitive.

Error:Authorizationfailed ondistributeddatabaseconnection attempt.

Consider whether or not you need torun your Domino server under adifferent LOCALE setting.

This message means theLEI job’s CCSID is notcompatible with theCCSID of the characterdata in the relationaltable being reference.For example you couldhave a job CCSID of 37and source data CCSIDcould be 937 (a doublebyte ccsid).

Error: Characterconversion cannotbe performed.

Check SQL statement.

This error is common if you cut andpasted SQL statement into activityfrom another source. Note that youcan now provide CR/LF charactersto improve readability. If the SQLstatement is correct, try retyping thestatement in the activity. You mayalso want to use the DB2 connectionoption for providing trace data in theactivity log. This may pinpoint whatis objectionable about the SQLstatement.

Non-display charactersin SQL statement

Error: Token wasnot valid. … (-104)

Activity EndedWith An Error

Possible SolutionPossible CauseError in Log


If the DB2 table is not journalled oniSeries, verify that the DB2connection you are using has thenon-journal option enabled. Thedefault setting for all LEI activities isto run with commitment control.Journalling is required to run undercommitment control. You mustcheck the non-journal option to turnoff this transaction dependency.

Most likely reason isthat the Journal optionis not correct in theconnection or the DB2table required to bejournalled.

See SQL7008 in theQSQLMSG message filefor other possibilities.

Error: <table name>in <library name>not valid foroperation. Function-Execute- (-7008)

Do a WRKRDBDIRE CL commandand determine if the target databaseis registered. If not, add the databaseand the necessary connectivityinformation to that data source. Notethat if you want to connect to thelocal DB2/400, a named entry for the*LOCAL database must be supplied.

Either the databasename provided in theDB2 connectiondocument is notspecified correctly (noteno longer casesensitive) or the nameddatabase is notregistered in the RDBdirectory.

Error: Relationaldatabase <databasename> is not inrelational databasedirectory.

Possible SolutionPossible CauseError in Log

Finding iSeries Job LogsThe primary source of information about a failing LEI server or activity isthe LEI log database. As LEI is a server addin, you may also need to checkthe Domino server console for any Domino related diagnostics. Occasion-ally you may need to find an iSeries system job log. Note that all LEI activi-ties run under the user profile QNOTES on the iSeries.

Enter the following command to find the job log:

WRKSPLF QNOTES

If there is no job log, you may need to change the Job Description for theexecuting Domino server to generate a job log and then reproduce thefailing request. To do this, find the job description associated with thesubsystem of your executing Domino server. For example, if your Dominoserver runs under subsystem DOMINO01, then the job description associ-ated with that Domino server is DOMINO01 (*JOBD) in libraryQUSRNOTES).

Enter the following command:

CHGJOBD QUSRNOTES/DOMINO01 LOG(4 10 *SECLVL)


The following are LEI-specific job names:

• LEI

• LEICSM

• LEIACT

The LEI job controls the overall LEI server, the LEICSM job communicateswith the LEI control store (the Administrator databases) and the LEIACTjob is the process that actually runs the activity. In addition LEI agents canrun under HTTP and Advanced RealTime runs under SERVER or HTTP.

There is another set of jobs that also factor into LEI running DB2-connectedActivities on iSeries. These are the QSQSRVR jobs. These are pre-startedjobs in the QSYSWRK subsystem that perform DB2 access in a thread safeenvironment on behalf of the activity job (LEIACT), the real time job(SERVER or HTTP) or the LEI agent job (AMgr). For each DB2 connectionestablished by the LEIACT, a corresponding QSQSRVR job in theQSYSWRK subsystem will be allocated to that connection and will performall the DB2 SQL requests on behalf of the activity job. It may be necessary attimes to find a QSQSRVR job log for problem determination. These jobs arepre-allocated under the user profile QUSER. It may be necessary to changethe job description associated with the QUSER profile in order to generate ajob log.

Additional Tips and Techniques for using LEI on iSeriesListed below are general tips when using LEI on iSeries.

• If you are building an activity that specifies subdirectories within yourDomino directory, remember that QNOTES must be authorized tothose directories and to use the forward slash (for exampledemodir/mydir/mydoc.nsf)

• Using the Create Metadata option when using a DB2 connection whenthe DB2 target table does not exist results in a CREATE TABLE for theDB2 target (for activities such as Direct Transfer and Replication).However, a CREATE TABLE done by LEI may not be desirable becauseLEI text fields are not delimited in size because they are mapped fromNotes text fields. When the fields are created in DB2, they can be verylarge. A CREATE TABLE will expand all undelimited text fields to fillout the maximum allowable relational record. On iSeries, this would becharacter fields that fill out what remains of a 32766 byte record.Although you can qualify the maximum text field size in the Notesconnection options, that text field size would apply to all undelimitedtext fields. You should create the DB2 table in advance or use aCommand Activity that creates the table with more reasonable CHARand VARCHAR field lengths.


• Do not set your LEI server polling interval too low - 60 seconds isreasonable; 5 or 10 is not.

• It is recommended that for Direct Transfer activities you set theNumber of Records to Transfer Concurrently to some number otherthan 1 for better transfer throughput. Depending on the transfer recordsize, this might be 20-100.

• If you are using replication with timestamp to replicate a DB2/400 tablewith a Notes database and your DB2/400 table is restored from backupor has had significant changes applied to it, such as throughAPYJRNCHG, you should select the Reset Replication Timestampbutton prior to the next run of the replication activity. Whenever yoususpect that the two databases are significantly out of sync due to asystem action or utility you should run with the reset option.

• Qualifying an LEI DB2/400 request by specifying a particular memberof the physical file is not supported. The first member of the specifiedphysical file (table) is always used.

• If you are taking the overwrite option on Direct Transfer and clearingout the target first, and that target happens to be a DB2/400 table, youmight want to consider using a command activity to clear the physicalfile member first (CLRPFM) and then do the direct transfer without theoverwrite option. This would eliminate the potentially lengthy SQLDelete and the additional journal entries that might occur. You couldthen schedule these two activities as chained (with direct transfer adependent activity of the clear request).

• To work around this situation, you may need to reorder the fields inyour form to reflect the order of the key fields as specified in the “KeyFields” option of your Replication Activity form or vice versa. Also, youshould not use a full timestamp field as a key field. DB2/400 precisionis more significant then is Domino’s precision when it comes totimestamps and you will not be guaranteed a unique lookup.

• On Direct Transfer, if you specify “Try Update Before Insert”, the keyfield(s) specified in the “Key Fields for Update” field must reflect thesource connection, and not the target connection key field names.

• Stored Procedures used on Direct Transfer requests or AdvancedRealTime activities must run in the activation group of the caller oniSeries (which is LEI). To determine the activation group state of yourprogram enter the command DSPPGM. If the Activation groupattribute is not *CALLER, you will get an abnormal termination in thelog database. In addition, the stored procedure must be invoked underthe authority of QUOTES user profile. Make sure that the program ismade available to public invocations or that QUOTES is authorized.


• With stored procedures to DB2, also note that NUMBER fields from aNotes form will be bound to argument values (in C) of type DOUBLEon a call to a stored procedure. Your stored procedure will need to castaccordingly in order to map to the appropriate SQL type.

Advanced RealTime Configuration, Troubleshooting, and Error MessagesThis section provides information about error messages, and knownproblems that you may encounter under certain conditions while usingAdvanced RealTime. For information about notes.ini variables forAdvanced RealTime activities, see the IBM Lotus Enterprise Integrator forDomino (LEI) Installation Guide.

Unable to Access Data with Virtual Fields Activities After UpgradingAfter upgrading from DECS to LEI, if you are unable to get data whenrunning Virtual Fields activities, open each Virtual Fields activity documentand ensure that the Domino server specified in the activity document iscorrect.

Security Issues in Advanced RealTimeThere are two issues regarding security in Advanced RealTime:

• Advanced RealTime administrator (Notes browsing and initialize keys)

• LC LSX against the Lotus Connector for Notes or the Lotus Connectorfor File System

The Advanced RealTime administrator issue occurs if you attempt tobrowse Notes when you create an activity or use the Initialize Keysfunction. This may generate a LotusScript error regarding access tounrestricted agents. Your Advanced RealTime activity must be allowed torun unrestricted agents for these capabilities to work.

The LC LSX issue occurs when agents or other LotusScript code, which usethe Lotus Connector for Notes or the Lotus Connector for File Systems,must be signed with a Notes ID that has permission to run unrestrictedagents. This also applies to any script libraries used by this code. Specifi-cally, connections through these Connectors will be blocked with an errorunless the signing Notes ID has permission to run unrestricted agents.


You can use either of the following solutions to address these issues.

• Add the ID “Enterprise Connector Products/Lotus Notes CompanionProducts” to the “Run Unrestricted Agents” field in the DominoServer’s entry in the Domino Directory (NAB) containing that server.This field is found under the Security tab.

• Resign the Advanced RealTime Administrator (LEI) database with aNotes ID that already has permission to run unrestricted agents. Resignthe Advanced RealTime Administrator through the DominoAdministrator client, not through the normal Notes client.

Instruction for configuring your Domino Directory is provided in the IBMLotus Enterprise Integrator for Domino (LEI) Installation Guide in the “SettingAccess Controls in the Domino Directory” section of each platform-specificchapter.

Stored Procedures in Sybase or OLEDB and Advanced RealTimeWhen attempting to create an Advanced RealTime Activity that uses storedprocedures in Sybase or OLE DB, you may find that the fields cannot bemapped and the following error displays:

Both the Notes and connection data field list must contain atleast one value.

The procedure can be selected, but the activity cannot be completed orsaved.

Sybase normally returns a result set from a stored procedure, which anAdvanced RealTime Activity “sees” as if it were a result set from a table orview. Because of this, when setting up an activity using a Stored Procedure,you must do the following:

1. Create the Advanced RealTime Sybase Connection Document byselecting Table, not Procedure.

2. Use or create a table containing the exact column names returned by thestored procedure, and use this in the mapping process in the AdvancedRealTime Activity.

3. Identify the stored procedure to use in the activity options under theappropriate “When Intercepting a document” section.

There are separate sections for the Open, Create, Update, and Delete eventsand separate stored procedures are needed for each event to performfunctions specific to that event. When the Advanced RealTime Activity isactivated, the stored procedure is used, overriding the field mapping.


Example:This example illustrates how to configure an Advanced RealTime activitywith a Sybase connection using stored procedures. It assumes that you havea Notes form with two fields, Key1and Lastname, and that you have Sybasetable(s) with many fields. It also assume that you have a stored procedurewhich accepts one input parameter and returns a result set with Key1,Lastname columns. Finally, it assumes that you have an activity whichreturns data based on the Open event.

Using this example, you will create a Sybase table, a stored procedure, andan Advanced RealTime Activity.

The Sybase TableFirst, create a Sybase table that has columns made up of what you areultimately mapping (the input parameter and the result set that your proce-dure uses).

For instance, in this example the dummy table would contain the followingcolumns:

Key1 VARCHAR(5)

Lastname VARCHAR(25)

The Stored ProcedureThe procedure takes input (the same as what you selected for the AdvancedRealTime key), and returns a result set that includes the key and allmapped fields in the Advanced RealTime Activity:

CREATE PROCEDURE dbo.proc1

(@Key1 varchar(5) ) -- Input. This key, matches key inActivity.

AS

BEGIN

select Key1, Lastname from debtest -- Result set. Returns allof

-- the mapped fields,including key(s).

where Key1 = @Key1

END

Note If you are working with Sybase, note that Sybase is generallycase-sensitive, but the @var (@Key1) in the Proc must have the same nameand match case with your Sybase column and Advanced RealTime mappedkey. Sybase will accept a different name/case if you execute the procedure


from an SQL tool, using Execute <Procedure>, but Advanced RealTimeneeds the name/case to be the same or it will return the error below:

03:48:27 PM ART: Monitor failure -- Error: Procedure proc1expects parameter @key1, which was not supplied., Connector'sybase', Method -Call- (201): proctest

Note In this example, Table was selected, not Procedure. Procedure isvalid only if you are returning all values using output parameters, as isdone with Oracle, for example.

In the above Virtual Fields Activity, dbo.proctable is a table created specifi-cally with the fields required for mapping. Once the events are selected,specify the procedure to be used under the Options, as shown in dbo.proc1.After inputting the procedure name on the activity document, pressing F9will refresh and show the input parameter that the procedure requires(Key1).

At this point, Virtual Fields returns the values in the mapped fields to theform being monitored. To use other events, create procedures appropriateto the event.

Note Since the stored procedure does not return all key values, “Initializekeys” does not work with this functionality; it does not recognize thecontents of a table or view. If key documents are required in Notes, createthem using an agent or by a separate Virtual Fields Activity that pulls thosekey values into Notes documents.

Advanced RealTime Activity Error MessagesError messages that pertain to Advanced RealTime Activities are listedbelow.

Cannot use field [‘FIELDNAME’] as both a key and a data field

Fields provided for Advanced RealTime activities must be either key fieldsor data fields - a field cannot be used as both in a single AdvancedRealTime Activity (although one field can be used as a key in one activity,and data in another activity). Remove any field that is used as both a keyfield and a data field from at least one of those lists.

Failure accessing shared RealTime Activities table

An internal error was encountered when attempting to access activity infor-mation. Record as much information as possible about the circumstancesand contact Lotus software technical support.


Unexpected internal failure in RealTime monitoring

An internal error was encountered when attempting to access context infor-mation. Record as much information as possible about the circumstancesand contact Lotus software technical support.

Update of key field [‘FIELDNAME’] is not permitted

Key values in a document were altered, but the Advanced RealTime Activ-ity indicated that changes to key fields should be blocked. Updates to bothNotes and the external system were aborted.

This record has changed in the back-end database since being opened -action cancelled

The Advanced RealTime Activity option to check the external system forchanges before writing changes to the back end was enabled, and the checkindicated changes in the back end. Since the document was opened, anothersystem or client changed the corresponding external record.

Cannot locate corresponding external record

The key values in the opened document being monitored by a AdvancedRealTime Activity did not correspond to a record in the external system.This error can be suppressed by selecting the Advanced RealTime Activityoption to create the external record if it doesn’t exist - instead of the error, anew record corresponding to the current Notes document data will becreated.

Failure compiling Filter Formula: FORMULA COMPILATION ERROR

The filter formula provided for the Advanced RealTime Activity failedcompilation. The compilation error is generated with the error message. Fixor remove the filter formula to successfully run the Advanced RealTimeActivity.

Failure compiling Pre-Open Formula: FORMULA COMPILATIONERROR

The pre-open formula provided for the Advanced RealTime Activity failedcompilation. The compilation error is generated with the error message. Fixor remove the pre-open formula to successfully run the Advanced RealTimeActivity.

Failure compiling Post-Update Formula: FORMULA COMPILATIONERROR

The post-update formula provided for the Advanced RealTime Activityfailed compilation. The compilation error is generated with the errormessage. Fix or remove the post-update formula to successfully run theAdvanced RealTime Activity.


Failure compiling Post-Create Formula: FORMULA COMPILATIONERROR

The post-create formula provided for the Advanced RealTime Activityfailed compilation. The compilation error is generated with the errormessage. Fix or remove the post-create formula to successfully run theAdvanced RealTime Activity.

Failure compiling Post-Delete Formula: FORMULA COMPILATIONERROR

The post-delete formula provided for the Advanced RealTime Activityfailed compilation. The compilation error is generated with the errormessage. Fix or remove the post-delete formula to successfully run theAdvanced RealTime Activity.

Unknown OS error: libdecsext.*

This is a Notes error reporting that Notes couldn’t load the extensionmanager library. Check that you have properly installed and configuredLEI. If problems persist, contact Lotus software technical support.

Realtime service addin task initialization failed

This indicates that the LEI addin task startup encountered an error. Checkthat you have properly installed and configured LEI. If problems persist,contact Lotus software technical support.

Realtime service is unable to allocate addin task resources

The Advanced Realtime service is unable to allocate additional resources.Check that you have properly installed and configured LEI. If problemspersist, contact Lotus software technical support.

Realtime service cannot connect to external system

You may not have the proper connectivity software installed that isrequired for accessing the external data system. Refer to the IBM LotusEnterprise Integrator for Domino (LEI) Installation Guide for information aboutthe native software required for connectivity to each of the LEI supporteddata sources.

Realtime service cannot find external table/metadata

The metadata selected for this activity does not exist in the external datasource.

Realtime service cannot find external procedure/transaction

The document open event captured by LEI encountered an error. The errordetails are logged to the Domino server log.


Realtime service error retrieving external record

The document open event captured by LEI encountered an error. The errordetails are logged to the Administrator activity log for this activity.

Realtime service error inserting external record

The document creation event captured by LEI encountered an error. Theerror details are logged to the Administrator activity log for this activity.

Realtime service error updating external record

The document update event captured by LEI encountered an error. Theerror details are logged to the Administrator activity log for this activity.

Realtime service error deleting external record

The document deletion event captured by LEI encountered an error. Theerror details are logged to the Administrator activity log for this activity.

Realtime service cannot locate the corresponding record in the externalsystem

The document key field values do not correspond to a record in the backend data source. The record in the external data system may have beendeleted.

Realtime service unable to update document due to key field changes;changes to key fields have been disabled

The key fields in the external data have been modified since the documenthas been opened. To allow key field changes, select the appropriate settingfor the option Key Field Updates in the Document Update options sectionof the Activity Document.

Realtime service is unable to update document due to conflict; the exter-nal record has been modified since being opened

The external data has been modified by another application since thedocument has been opened. Close and reopen the document.

Realtime service error storing external attachment

There was a problem storing the attachment portion of the document to theexternal data store.

Realtime service error retrieving external attachment

There was a problem retrieving the attachment portion of the documentfrom the external data store.


Realtime service cannot locate the attachment in the external system

There was a problem locating the attachment portion of the document inthe external data store.

Realtime service data overflow accessing external record

For document open events, this indicates that data in an external field wastoo long. Usually this is due to text longer than 64K. To avoid this problem,change the Notes field to Rich Text. (See the error in the Administratoractivity log for this activity for information on which field caused theoverflow.)

For document updates and inserts, this message indicates that thedocument data overflowed a back end field. You may need to change thedata type in the back end to store large amounts of data.

Realtime service error deleting external attachment

There was a problem deleting the attachment portion of the document fromthe external data store.

Realtime service error browsing the external system

There was a problem retrieving information about the names of tables in thedatabase, or retrieving the datatype information about the columns in aparticular table.

Realtime service encountered a missing or invalid Data ConnectionResource

You get this message when you are using the Domino Designer DataConnection Resource (DCR). The Data Connection Resource that wasreferred to by one or more of the fields on the form is not valid, or could notbe located.

Realtime service error scanning the external system. Some externalrecords may have been ignored

During a view refresh, an error occurred when retrieving document infor-mation from the external data store.

Realtime service error loading external agents/design elements

An error occurred while accessing a virtual agent.


This application uses a Realtime Service Activity which is currently notrunning. Contact your Notes administrator.

During an attempt to open or delete a document, a needed runningAdvanced Realtime activity could not be found. Verify that the activitymonitoring this database form is running. If so, fully refresh your view(Shift F9) in the possibility that the external data source record has beendeleted. Also check the activity log for any additional error information.


Appendix C Tutorials

This chapter provides tutorials for building some of the LEI Activities. Youcan use these tutorials to learn how to build these LEI Activities.

Introduction to the TutorialsThe examples in this appendix guide you through the process of buildingseveral LEI Activities, including the connections that they use. Theexamples use sample Notes databases supplied with LEI.

The examples use an existing Notes database as the source connection. Thetarget connection can use any Lotus Connector in your environment thatyou choose. LEI will create new metadata objects (tables or Notes forms)when transferring or replicating data from the Notes database to the targetdatabase.

The tutorials in this appendix address the following tasks:

• Building a Direct Transfer Activity

Build an activity that transfers data from a sample Notes database to adatabase of your choice.

• Building a Polling Activity

Build an activity that polls a sample Notes database for a condition andthen triggers a direct transfer Activity.

• Building a Replication Activity

Build an activity that replicates a sample Notes database to a databaseof your choice.

• Building a Scripted Activity

Build an activity that employs the two agents supplied in the LEI ScriptVault (leivlt6.nsf) in conjunction with the supplied leipackagetrack.nsfsample database.

Build an activity to execute LotusScript commands for greaterfunctionality with your data transfers.

321

• Building an Advanced RealTime Activity

Build an activity that monitors external system data in real timethrough a Notes application.

Build an activity that queries dynamically using your Notes or Webbrowser.

• Additional Advanced RealTime Examples

Build a Virtual Fields or Virtual Documents activity that uses VirtualAttachments.

Using filter formulas, storage options, monitor orders, and storedprocedures in Virtual Fields activities.

After building these examples, you will have scheduled Activities thatcould continue processing. You may want to delete or disable the Activityschedules when you’re done with the examples.

AssumptionsThe tutorials assume that you have a working knowledge of Lotus Notes. If needed, you can refer to the Notes online Help for assistance.

These tutorials also assume that you have installed LEI and all theconnectivity software required for your system data sources.

Finally, the tutorials work in a linear fashion, building on activities andconnections created at the start of this appendix.

Before BeginningBefore beginning, you will need to have the LEI Administrator and logdatabases on your Notes client desktop.

You will also need to know on which server the LEI sample databasesleiempsamp.nsf and leipackagetrack.nsf are located, as well as the LEIScript Vault (leivlt6.nsf). These databases are supplied as part of the LEIinstallation. They will be on the LEI server machine and will need to becopied to a Notes server. These databases should also be added to yourNotes desktop, since you will modify them in these tutorial exercises.

Be sure that the LEI server is running and can communicate with allexternal data sources that you intend to use. See the IBM Lotus EnterpriseIntegrator for Domino (LEI) Installation Guide for information aboutconnectivity requirements and testing connectivity to your data sources.


Building a Direct Transfer ActivityThis section describes the steps in creating a Direct Transfer Activity. Itdescribes the general procedure for setting up and executing a transfer ofdata from a Notes database to another database.

The main steps in performing a Direct Transfer Activity are listed below:

1. Create the Connections.

2. Create the Direct Transfer Activity.

3. Run the Activity.

4. View the Log.

Step 1: Create the Connection DocumentsBefore you create an Activity, you must create the Connections that theActivity will use. A Connection defines access to a database that LEI willinteract with. A Direct Transfer Activity requires a source databaseconnection and a destination database connection.

Note You should have already established connectivity to any databaseyou intend to use. The Lotus Connectors and Connectivity Guide describes thatprocess.

Creating the Source ConnectionIn this example, the source Connection is the sample Notes databaseleiempsamp.nsf, which is located in the help directory. To create the sourceConnection, follow these steps:

1. Start Lotus Notes and open the LEI Administrator databasedecsadm.nsf.

2. From the LEI Administrator click Add Connection — Connection toNotes.

3. In the Name field, enter a descriptive name that you can use later toidentify the Connection in a list. You’ll use this name to pick theConnection in the course of creating the Direct Transfer Activity. Forthe purposes of this example, enter Sample 1 Source.

4. Enter the name of the Notes server on which the Notes databaseleiempsamp.nsf is located. Leave this field blank if the database is local.

5. Enter the Notes database name leiempsamp.nsf.

Appendix C: Tutorials 323

6. Enter the Category name of Samples. By assigning this category to yoursample documents, you will find it easier to manage those documentsas a set. This is a practice you may find helpful when using LEI.

7. Save and exit the document.

Creating the Destination ConnectionThe Destination Connection Document that you create depends on thedatabase that you choose for the destination. To create the Connection,complete the following steps:

1. From the LEI Administrator, click Add Connection. Choose thedestination database type from the resulting list.

Note This is the target database in which LEI will create a metadata toreceive the data.

2. In the Name field, enter Sample 1 Destination.

3. Complete the remainder of the document as needed. You must enterthe location of the database and may need to enter a user name andpassword for access.

4. Enter the Category name of Samples.


Now that you’ve created the two Connection documents, you can examinethe Connections view to make sure that they were created.

Viewing the ConnectionsThe Activities and Connections view displays your activities and Connectionsby Name. It can also display names by category. To view the Connections bycategory, do the following:

1. In the Navigator bar of the LEI Administrator, expand the Activities byType option. Click on the By Category option and expand the Samplescategory type.

2. Expand the Link subcategory until you see the Sample 1 Source andSample 1 Destination connections you created.

Note To edit those Connections, you can double-click the document namein the view and then enter edit mode by pressing Ctrl+E or double-clickingwithin the document.


Step 2: Create the Direct Transfer ActivityAfter defining the Source and Target Connections, you can create the DirectTransfer Activity to transfer data from one database to the other. Completethe steps below to create the Direct Transfer Activity.

1. From the LEI Administrator, click Add Activity and select DirectTransfer from the resulting list.

2. Enter the Activity name Sample Transfer in the Name field.

3. Identify the Source and Target Connections:

• Use the drop down button for a list of the available Connections orpress Enter with the cursor in the Connection Name field.

• From the list of Connections, select Sample 1 Source.

• Repeat for the Connection Name field under Target, selectingSample 1 Destination.

4. In the Form field under Source, enter the Notes form Emps.

5. In the Table field under Target, enter the table name, Employees.

6. The Select Statement field specifies the data you want to transfer. Thestatement can be a SQL query or, for a Notes source database, aselection formula.

For this example, enter the following Notes formula: SELECT @ALL

This formula will create a result set identical to that of the set ofdocuments associated with the Notes form Emps.

7. In the Field Mapping Section, choose Automatic and verify that ByName is selected.

8. Click the Target Data Options tab.

9. In the Existing Data Options section, enable the Create Target Metadataoption to create a new table for the transferred data. Leave the otheroptions as they are.



This completes the process of creating a Direct Transfer Activity.

Because the Activity’s schedule was not enabled when you closed thedocument, you’ll have to manually launch it.


Step 3: Run the ActivityNext, you’ll launch the Activity manually and use the Active view todisplay its status. To launch the Activity and view the list of runningActivities, do the following:

1. In the LEI Administrator, expand the Activities by Type option. Clickon the By Category option and expand the Samples category type in theview.

2. Expand the Activity subcategory until you see the Activity you created.

3. Highlight the name of the Activity that you just created, SampleTransfer, and click Start.

You can alternatively click Start at the top of the actual ActivityDocument to execute the Activity.

Viewing the Activity StatusThere are three main ways to display an Activity status.

• Click the Activities by Type option in the LEI Administrator Navigatorpanel. All existing Activity names display, along with their currentstatus.

• Expand the Activities By Type option in the LEI AdministratorNavigator panel. Click Data Management to display a more detailed listof all existing Activities and their current status.

• Expand the Activities By Type option in the LEI AdministratorNavigator panel. Click By Category. Click a category type, for exampleDirect Transfer, to display the current status of only the Direct TransferActivities.

If you do not see a specific Activity listed, press F9 periodically until thatActivity name appears as a scheduled job. If you still do not see the Activitylisted, it may have already completed. You can view the Log to learn aboutActivities that have already run.


Step 4: View the LogThe LEI log documents the process and outcome of each Activity.

There are three ways to view the log:

• Click the View Log button on the individual Activity Document

• Highlight an Activity in the Activity view and click the Log button inthe action bar

• Click the Log option on the LEI Administrator Navigator

Note If you open the Log from the Activity Document, LEI displays theLog entry describing the latest execution of the Activity.

For this example, once the Activity has completed, highlight the SampleTransfer Direct Transfer Activity in the Activities view and click the Logbutton in the action bar above the Activities view.

Building a Polling ActivityThe steps described here give you the overall procedure for polling. Pollingis a way of initiating one or more Activities based on a condition. Once thePolling Activity is running, it checks a selected database at regular specifiedintervals looking for a particular condition. When the condition returnstrue, the Polling Activity executes one or more other Activities. The PollingActivity can be thought of as a trigger for other Activities.

In this example, the Polling Activity will trigger a Direct Transfer Activity.

Step 1: Create the Polling ActivityThe Polling Activity requires a Connection identifying the database to bepolled. Instead of creating a new Connection for the purposes of thisexample, we’ll use the existing Connection Sample 1 Source.

You’ll schedule the Polling Activity to run between 8 AM and 5 PM eachday. During that period, it will poll the database once a minute.

Complete the following steps to create the Polling Activity.

1. From the LEI Administrator, click Add Activity. Select Polling from theresulting list.

2. Enter the Activity name Sample Polling in the Name field.


3. Identify the database to be polled by selecting the connection namedSample 1 Source.

Note This connection was created in the previous section entitled,“Building a Direct Transfer Activity”. If you have not already createdthis connection, do so now following the instructions in the previoustutorial of this appendix.

4. In the Table or Form Name area just under the Connection Name field,enter Emps.

5. Enter the Trigger Statement SELECT HIREDATE=@TODAY. Currentlyno record satisfies this condition, but you’ll add such a record once theActivity is created.

6. Leave Polling Frequency unchanged so that the polling occurs every 60seconds.

Note This frequency value does not determine when the PollingActivity actually runs. As with other Activities, that is determined bythe schedule.

7. At Activities to Execute, select the Activity named Sample Transfer.This is the Activity that will be executed when the Command Statementreturns a true condition (for example, once you add a new record thatmeets the condition).

Note This Activity was created in the previous section entitled,“Building a Direct Transfer Activity”. If you have not already createdthis Activity, do so now following the instructions in the previoustutorial of this appendix.

8. For this example, leave the Reset Trigger information as is.

9. Click the Error Handling Options tab and enter the Maximum EventCount of 1. Leave other options unchanged.

Note This value specifies the maximum number of times thatActivities will be executed as a result of a true condition before theActivity terminates. Each true condition and associated executioncounts as one event. Zero sets no limit on the number of times thatevents can occur.

10. Click the Activity Execution Options tab to optionally designate an LEIserver on which to execute the Activity. Leave other optionsunchanged.


11. Click the Scheduling tab and set the Schedule field to ScheduleEnabled.

Note For a Polling Activity, scheduling behavior is slightly differentthan with other Activities. Other Activities conclude once they completetheir processing. Unless otherwise configured, however, a PollingActivity keeps running (and polling) once it’s initiated. As a result, theRepeat Interval (how often the Activity is initiated) need not be morefrequent than the window of time within which the Activity can run.That window of time, in this case, will be defined in the next step asbeing from 8 to 5 daily.

12. By default, Repeat Interval is set to every 60 minutes. Change theRepeat Interval to every 1 (one) Day.

13. In the Run at Times field, enter 8:00 AM - 5:00 PM to have the Activityexecute within that range of hours. Given the Repeat Interval of oneday, the Activity will start polling at 8:00 AM and stop polling at 5:00PM. According to the Polling Frequency defined earlier, it will pollevery minute within that period of time.

Note If you are creating this example outside that time, use a rangethat includes the current time.




16. View the Samples Polling Activity using the By Category displayoption.

In the next section, you’ll create a record that will cause the pollingcondition to become true and queue Sample Transfer to be run.

Step 2: Cause the Polling Condition to be TrueTo create a true condition and cause the Polling Activity to schedule thesubordinate Activity, do the following:

1. Open the supplied sample database leiempsamp.nsf, located in the helpdirectory.

2. Create a new document in the sample database by selecting Create -Emps from the Notes menu.

3. Enter the following information in the form:

EMPNO 7790

ENAME NNOTES

JOB ENGINEER

MGR 7791

HIREDATE 9/12/01 (enter today’s date)

SAL 1000

COMM

DEPTNO 72

Note This document will satisfy the polling condition: SELECTHIREDATE = @TODAY.


4. Save and close the form.

5. Start the Activity.

6. Check the LEI Administrator to see that the Activity correctly initiatedSample Transfer. Check the log for the status of the Activity.

Note The Polling Activity will continue until it is manually disabledby stopping the activity manually and disabling the schedule.

Step 3: Clean up the SamplesAfter trying out these examples you can delete the Connections andActivities. Alternatively, you can disable the Activities, which will allowyou to reuse them later on.

Deleting the Samples Category Connection and Activity documents1. In the LEI Administrator, display By Category.

2. Click the Samples arrow to display it contents. Continue displaying itssubcategories until the names of the sample activities appear.

3. Select the documents to delete and press the Delete key or Ctrl+X onyour keyboard.

4. The documents will be deleted when you leave the view.

Disabling the Sample Activity Documents1. In the LEI Administrator, display By Category.

2. Click the Samples arrow to display it contents. Continue displaying itssubcategories until the names of the sample activities appear.

3. Select the first Activity document to disable.

4. Press Ctrl+E to edit the document.

5. Under the Scheduling tab, change the Schedule field to ScheduleEnabled.

6. Save and close the Activity.


Building a Replication ActivityThese steps described the overall procedure for configuring and executingdatabase replication. The databases used are the LEI sampleleiempsamp.nsf and a second database of your choice.

The type of replication shown in this example is called “primary key”. It is a method of replication that compares one or more key fields in thereplicating database (Source) and the one to be replicated (Target). Bycomparing key fields, LEI matches records and determines whetherreplication requires a record update, insert, or delete operation. An updateoccurs when the primary keys of both records are identical (assuming thedata in the other fields is not), an insert occurs when the primary key existsonly in the source, and a delete when it exists only in the target.

Step 1: Prepare the DatabaseIn this example, you will use the same database as in the preceding tutorial(entitled “Building a Polling Activity).” By adding a document to thesample Notes database, you will be able to see how the replication works.The record will be replicated to the other database.

1. Use the Notes desktop to open the supplied sample databaseleiempsamp.nsf.

2. Create a new document in the sample database by selecting Create -Emps from the Notes menu.


3. Enter the following information in the form:

EMPNO 6627

ENAME JNOTES

JOB ENGINEER

MGR 6628

HIREDATE Today’s date

SAL 1000

COMM 0.05

DEPTNO 70

4. Save and close the form.

Step 2: Create the ConnectionsCreate a Notes connection and a second connection to a database in yourenvironment. You will identify the source database (the one against whichthe other database is replicated) when you build the Replication Activity.

Creating the Source ConnectionThis first connection will identify the Source database. To create the connec-tion complete the following steps:

1. From the LEI Administrator, click Add Connection - Connection toNotes .

2. In the Name field, enter Sample 2 Master.

3. Enter the name of the Notes server where the sample database islocated.

4. Enter the name of the sample Notes database leiempsamp.nsf, which islocated in the help directory.

5. In the Category field, enter Samples.


6. Leave all other options set to their default values.

7. Save and close the document.

Creating the Target ConnectionThis second connection will identify the target database. In this example,the data in the target will be updated as a result of the replication. To createthe connection complete the following steps:

1. From the LEI Administrator, click Add Connection.

2. Select the database type that you want to use from the resulting list andclick OK.

3. In the Name field, enter Sample 2 Updated DB.

4. Enter the name of the database that you want to have updated based onthe information in the Source database. For this example, this databasewill be named CurrentEmployeeData.nsf. This database was created asa copy of the supplied sample database leiempsamp.nsf and resides onthe local LEI server in this example.





Step 3: Create the Replication ActivityOnce the two connections are created, create the Activity that will replicatethe source database. Data is replicated at the table level (or at the Notesform level).

In this example, you will schedule the Activity to run every hour andrestrict the range of time within which it can run.

Complete the steps below to create the Replication Activity.

1. From the LEI Administrator, click Add Activity. Select Replication fromthe resulting list.

2. In the Name field, enter Sample Replication.


3. In the Source Connection field, specify Sample 2 Master.

4. In the Target Connection field, specify Sample 2 Updated DB.

5. Enter the Form Name for both Connections. Enter Emps for the SourceConnection and Sample1 for the Destination connection.

6. Enable Automatic Field Mapping.

7. For the Source Key value, enter Empno.

8. For the Target Key value, enter Empno.

9. Enable the Mapping by Name option.

10. If the databases that you identify for replication keep the date and timeof each change to a record in a timestamp field, you can identify thosefields and do primary key/timestamp replication. Leave TimestampReplication deselected for this example.

11. Click the Data Options tab and then select Reduced-precisionComparison.

Note If the source database uses a different precision than the targetdatabase for datetime or floating point numbers, false mismatches mayoccur. This option prevents that by using a lower common degree ofprecision. Datetime values are compared to the second and floatingpoint numbers to ten digits of precision.

12. The Conditional Clause for the Source Connection could be a Notesformula or SQL WHERE clause to further limit the result set. Leave thisfield blank for this example. For this example, do not enter a conditionclause.

13. Optionally click the Activity Execution Options tab to specify an LEIserver on which to execute the Activity. Otherwise leave these optionsset to their default values.

14. Click the Scheduling tab and then select Run Activity Once and Disable.This option only allows the replication to run just once as a trial, afterwhich its schedule is automatically disabled.

15. Change the Schedule field to Schedule Enabled.


16. Limit the times and days on which the Activity can run. For thisexample, do the following:

• In the Run at Times field, enter 7:00 AM - 5:00 PM to have theActivity execute only within that range of hours.

• Schedule the replication to run every hour. Enter 60 in the RepeatInterval field and select Minutes.

• In the Days of Week field, delete today’s day name and tomorrow’sby clicking the down arrow and then deselecting the appropriatedays of the week.

With these settings, the Activity will not run until 7:00 AM on theday after tomorrow.





Checking Activity Status and Running the ActivityCheck the status of the Activity in the LEI Administrator.

1. In the LEI Administrator, choose Active from the Navigator.

2. Locate the Activity you just built, Sample Replication.

3. Select the Activity.

4. Select Start from the LEI Administrator.

Note To test the Activity and your scheduling specifications, you canselect Trial Run Replication, within the Activity Document, to performa test run prior to actually executing the Activity.

5. Periodically press F9 to refresh the view until the Activity completes.

Note After the Activity completes, it will be scheduled for 7:00 AM theday after tomorrow (in this example on Thursday). The Run ActivityOnce and Disable option only pertains to a scheduled run.

6. Open the target database to see the data changes that were made basedon the contents of the source database.

Building a Scripted ActivityThis section describes the steps in creating a Scripted Activity. It describeshow to set up and run an activity that will execute an LSX agent.

An agent can consist of one or more simple actions or formulas to manipu-late data in your databases, custom LotusScript commands to perform anumber of different functions, or Java statements, each of these possibilitiesproviding greater functionality to your LEI Activities.

Note If you have installed LEI but not yet migrated your LEI Release 3.nscripts from LEI LSX format to LC LSX format, you should perform thatmigration now, prior to attempting to use those past-version scripts. TheLEI LSX format has been retired and LEI LSX format scripts are no longeruseable in LEI.


Example 1This example demonstrates how to access, edit and use two scripts (agents)that are supplied and installed in the LEI Script Vault (leivlt6.nsf). Both ofthese scripts will access the sample package tracking database(leipackagetrack.nsf) supplied with LEI.

The first script will perform a direct transfer from the DATA form in theleipackagetrack.nsf and create and insert this data into a new form or table(depending on the target).

The second script will perform a keyed replication between the two tablesfrom the Direct Transfer Activity.

There are two ways to access the supplied agents where the scripts arewritten.

• Open the LEI Script Vault leivlt.nsf from the Notes desktop.

Right-click and select Open (database) from the resulting menu. Selectyour server and then select the LEI Script Vault (leivlt6.nsf). The iconwill be placed on your desktop. Right-click on it and select “Open inDesigner.”

Choose File - Database - Open from the Notes top bar. Specify theserver name and .nsf file name (or database icon) from the resultingmenu and then click Open. Once the database is open, choose View -Design to open Domino Designer. Select Agent from the DominoDesigner Navigator.

• Start Domino Designer and then open the LEI script vault.

Choose File - Database - Open from the Domino Designer top bar.Specify the server name and .nsf file name (or database icon) from theresulting menu and then click Open. Expand the Shared Code sectionand select Agent from the Domino Designer Navigator.

To see the code for a specific agent, double-click on the agent name inDomino Designer. The code is categorized under the terms Options,Declarations, Initialize, and Terminate.


Step 1: Create the Connection DocumentsIn this step, you will create Connection Documents to the source packagetracking database (leipackagetrack.nsf) and to the target database, which inthis case is the sample employee database (leiempsamp.nsf).

Creating the Source Connection1. From the LEI Administrator, click Add Connection - Connection to

Notes.

2. In the Name field, enter Packagetracking.

3. In the Notes Server field, optionally enter the name of your server orleave blank if your server is local.

4. Specify the Notes Database file name leipackagetrack.nsf.



Creating the Target Connection1. From the LEI Administrator, click Activities - Add Connection -

Connection to Notes - OK.

2. In the Name field, enter myNotes.

3. In the Notes Server field, optionally enter the name of your server orleave blank if your server is local.

4. Specify the Notes Database file name leiempsamp.nsf.


Step 2: Create the Direct Transfer Activity1. Open the Package Tracking database by selecting File - Database - Open

from the Notes top bar. Specify the server name and leipackagetrack.nsffile name from the resulting menu and then click Open.


2. Click on the “All documents” view. You will use information from the“Data” key.


3. Open the LEI Script Vault (leivlt6.nsf) in Domino Designer.

4. Double-click the “PackageTrack Direct Transfer” agent.

Note The code for a specific agent is categorized under the termsOptions, Declarations, Initialize, and Terminate. The Declarationssection contains all the pertinent information for the agent to runcorrectly (for example, this contains the name of the Source connectiondocument). The script itself is written in the Initialize section.Comments are added where appropriate.

5. At this point, you will create the Scripted Activity to call your LSXagent. In the LEI Administrator, select Add Activity - Scripted.

6. In the Name field, enter Direct Transfer.

7. In the Agent Server field, enter the name of your server. Leave this fieldblank if your server is local.

8. In the Agent Database field, enter leivlt6.nsf (LEI Script Vaultdatabase).

9. For the Agent Name, enter Package Tracking Direct Transfer.



14. Check the LEI log and you will see that eight records have been fetchedfrom all connections (source), and eight records have been inserted intoall connections (target).

Step 3: Perform Primary Key ReplicationIn this script, you will perform a replication from the leipackagetrack.nsfdatabase to the leiempsamp.nsf database. The script being used in this stepis called “PackageTrack Primary Key Replication,” and can be viewed inDomino Designer.

1. Open the leipackagetrack.nsf database in your Notes client.

2. Choose Create and then Package.

The following form appears.

3. Add your own information to the Package Tracking Data entry form.


5. Create a Scripted Activity to call this script by selecting Add Activity -Scripted from the LEI Administrator.

6. In the Name field, enter Replication.

7. In the Agent Server field, enter the name of your server. Leave this fieldblank if your server is local.


8. In the Agent Database field, enter leivlt6.nsf.

9. In the Agent Name field, enter Package Tracking Primary KeyReplication.






14. Check the LEI log. You will see that seventeen records have beenfetched from all connections (source and target), and one record hasbeen inserted into all connections (target).

Example 2This example demonstrates how to perform a simple action on data in thesample database leiempsamp.nsf using a Scripted Activity.

Step 1: Create the AgentThere are two methods to create an agent in the database leiempsamp.nsf.From within leiempsamp.nsf you can choose Create - Agent from the Notesmenu or you can choose the Create Agent button when creating theScripted Activity Document. For this example, you will create the agentwhen you create the Activity.

1. Use the LEI Administrator to create a new Scripted Activity.

2. In the Name field, enter Scripted ActivityA.

3. Click the Create Agent button at the top of the document.

4. A dialog box will prompt you for a server name if the default servername has been removed. Enter the server name where the databaseleiempsamp.nsf is located.

5. A dialog box will then prompt you for a database name in which tocreate the agent. Enter leiempsamp.nsf.

6. An Untitled agent window opens.


7. In the Name field, enter Job Script.

8. In the Runtime Target field, specify all documents in database.

9. Close the property box.

10. Click the Add Action button at the bottom of the window. An AddAction box will appear.

11. In the Action field, specify Modify Field.

12. In the Field field, specify JOB.

13. In the Value field, enter ENGINEER.

14. Select Replace value.

This action will replace the value in the JOB field for each document inthe leiempsamp.nsf database.

15. Click OK.

16. Save and close the agent. The leiempsamp.nsf database remains open.


Step 2: Complete the Scripted Activity Document1. Press Escape to return to the Scripted Activity that you created.

2. Click the button in the Agent Name field and choose Job Script from thelist of agents.

Note If you want to have a specific LEI server execute the activity,specify the name of that server in the Designated Server field under theActivity Execution Options tab.

3. Enter the Category Samples.



Step 3: Start the ActivityTo run the activity and view it, complete the following steps.

1. Display the Samples category of Activities in the LEI Administrator.

2. Select the Scripted Activity that you just created (named ScriptedActivityA).

3. Click Start from the LEI Administrator.

4. You should see Scripted ActivityA begin to execute.

Step 4: View the Log and Activity Results1. When the Activity is complete, select its name from the LEI

Administrator and click Log. The activity should be logged as “Started”and “Finished.”

2. Open the leiempsamp.nsf database and notice the Job field. Eachinstance has been replaced with the value “ENGINEER.”


Building an Advanced RealTime Virtual Fields ActivityThe most common use for Advanced RealTime Virtual Fields activity is togive access to external system databases such as DB2, Oracle, or Sybase, toNotes users. This section provides an example of how to give Notes usersinformation about employees, where the employee information is stored inan external system database and might look something like theleiempsamp.nsf sample database supplied with LEI. The EMPNO key fieldand the ENAME, HIREDATE, SAL, JOB, and DEPTNO data fields are used.

You can perform the steps in this example yourself by transferring thisNotes data to an external system database, if you have not already done so,using an LEI Direct Transfer Activity. The process for creating an LEI DirectTransfer Activity was described in a previous section, “Building a DirectTransfer Activity.”

Note To operate the Advanced RealTime Activities, the LEI server must beinstalled on the same Domino server as the Notes database that Notesend-users will access for Advanced RealTime lookups.

Follow these steps to create a simple Advanced RealTime Virtual Fieldsapplication.

Step 1. Gather the Necessary InformationIdentify the table name, description (metadata) and necessary user nameand password in the external system database. If you followed the previousDirect Transfer example, the table name is Employees, the field names areas above, and, of course, you know the user name and password needed forthe external system database.

Step 2. Create the Form in the Notes DatabaseCreate a form in the Notes database having corresponding fields for thekey(s) and data fields. The field names do not need to match those used inthe external system database, however the datatypes should match.

Enter a form name of your choice.

Create a view from which you will later select documents. For this example,use the view name “Employee Lookup.”

Step 3. Create the Connection DocumentsCreate a Connection document to the external system database using theinformation gathered in step 1 above, or reuse one that you created for aprevious example, Sample 1 Destination.


Step 4. Create the Virtual Fields ActivityCreate the Virtual Fields activity in the LEI Administrator using the aboveConnectors. Map the key and data fields that correspond. This VirtualFields activity example uses the “Document Open” Monitor, which causes alookup against the DB2 table EMPLOYEE when end-users open the formEMPS with only the keyfield EMPNO populated.

Step 5. Initialize the Keys in the Notes DatabaseClick the “Initialize Keys” button in the Virtual Fields activity document.The Notes database above must be initialized by creating key documents,which contain the keys that refer to the records in the external systemdatabase. Do this by initializing keys.


Step 6. Start the Virtual Fields Activity1. Return to the LEI Administrator database and use the Activities view to

locate your activity.

2. Either choose Start or open the Activity and establish a schedule forwhen the Virtual Fields activity will be operational for Notes end-users.

3. Enable the schedule, and save the document.

Note The Virtual Fields activity will continue to run until you eitherstop it by choosing Stop or the schedule expires.

4. Refresh the Activities view until the Activity status icon becomes abeacon. This icon indicates that the activity is now running.

Step 7. Use the Virtual Fields ActivityUse the application by opening the monitored Notes database and openingone of the documents containing a key value.

The first open will take longer because the connection has to first be estab-lished with the external system data base. The data fields are thenpopulated by the Virtual Fields activity from the external system database.

This completes the example of using a Virtual Fields Advanced RealTimeactivity.

Building a Dynamic Advanced RealTime Virtual Fields Query for Notes orWeb Clients

This section provides information about using your Notes client or Webbrowser to invoke a Virtual Fields activity that accepts a key value input bythe user for querying an external data source. This example shows how toextend the functionality of the Advanced RealTime activity to provide adynamic query capability.

Example Contents and SetupIncluded with your LEI installation disk is a sample databaseleipackagetrack.nsf. This database provides the Lookup and Status formsused in the example. The database also includes sample raw data that maybe used to populate your external system database for use with theexample.


OverviewThere are several pieces needed to create Advanced RealTime Virtual FieldsDynamic Notes or Web based queries:

• An external system database containing the information that you wantto present to users in Notes

• A Notes database on your Domino server, such as leipackagetrack.nsf

• A Virtual Fields (or Virtual Documents) activity which resides on thesame Domino server and connects the two

To follow this example you will move the sample data to the externalsystem database, create two forms and a view in your Notes database, andthen you will create a Virtual Fields activity to monitor the Notes database.This example database has the necessary forms and views if you do notwish to create them yourself.

Step 1. SetupCopy the leipackagetrack.nsf database to a directory on the Domino serverwhere LEI is installed.

Note To modify the forms, open leipackagetrack.nsf in Domino Designer.

Step 2. Create or Choose an External System Database to MonitorWithin the leipackagetrack.nsf database there is data on packages that canbe transferred to your external system database. These documents orrecords have been created with the Package form and can be viewed withthe Packages view. You can use LEI to move this data to your externalsystem database, or choose another similar table of your own, or create thetable. The key field named “CODE” is what is important here. If you areusing a table of your own, identify the key field you want to use for lookupsand use it in the appropriate places in the later steps. This example usesPackageID on the Notes side to illustrate that the field names need not bethe same in both databases.

If you use an LEI Direct Transfer Activity to move this data to Oracle, selectthe option for “No Long Column” in the Connection document. Otherwisethe first text column will be made a LONG in Oracle.


Step 3. Create the Lookup Form in the Notes DatabaseIf you are using leipackagetrack.nsf, you can use the form “Lookup”included in this database. The key field that will be used by LEI for thelookup is what is important here. In this example it is PackageID. You canput information on this form to guide the user.

Note There is a view “Query” referred to in the following formula; youwill need to create that view after the “Lookup” form is completed.

There is a button in the form for “Lookup Package” that contains thefollowing formula:

@PostedCommand ([FileSave]);

@PostedCommand ([FileCloseWindow]);

@PostedCommand ([FileOpenDatabase]; @DbName; "Query";@Text(PackageID));

@PostedCommand ([OpenDocument])

This code is used when running the application from Notes but is ignoredwhen running the application from the Web.

Note The create event should not be monitored when performing dynamicqueries. This can lead to an unwanted record being inserted in the externalsystem or the error “duplicate key value specified.”

1. Save the document with the PackageID that the user wants entered intothat field.

2. Close the window.

Note If you do not close the window, an orphaned “Untitled”document is left.

3. Locate the document in the Query view where the indexed key fieldPackageID is the same as the one just saved.

4. Open the document. The view selection formula will then display theStatus form.


Description of How this WorksFrom the Web, Domino will treat the button as a POST command and willcreate a document in the database and then respond to the formula in the$$Return field, which should be hidden. The $$Return field will generate aURL that will open the newly created document in a view called Query justas it happens with the Notes client.

In this example, the $$Return field contains the following:

@If (PackageID="";

"Please supply a tracking number before pressing theLOCATE button";

"[/" + @Subset (@DbName; -1) + "/Query/" + PackageID +"?OpenDocument]"


Step 4. Create the Status Form in the Notes DatabaseCreate another form to return the information to your user. In the exampleit is called “Status.” This form must also use the key field “PackageID.” TheVirtual Fields activity will be asked to “Monitor any form;” it will respondto the opening of this “Status” form when the original document created bythe user is opened from the view, “Query.” By using a Form Filter formula(described in Step 7) only the two forms of interest will trigger the VirtualFields activity.

Step 5. Create the Query View in the Notes DatabaseYou will need to create a view to find the document that was just created inthe last step. This view must be indexed on the key field, in the examplePackageID.

The view selection formula is:

SELECT (@Contains(Form; "Lookup"))

Under the View Properties Advanced tab, put the following formula:

@If(@IsNewDoc;"Lookup"; "Status")

This will switch the form used to the Status form when opening a documentthat has been saved using the Lookup form.


Step 6. Create the Connectors to the Source and External SystemDatabases

You will need two LEI Connectors; one to the external system database:

And one to the Notes database being monitored by Advanced RealTime:


Step 7. Create the Virtual Fields ActivityCreate the Virtual Fields activity in the LEI Administrator that will monitorthe Notes database for Open events. This activity will use the Connectiondocument created in step 3 of the previous example, “Building anAdvanced RealTime Virtual Fields Activity,” to link the external systemdatabase to the Notes document using the key field you have chosen. In thiscase the key field in Notes is PackageID and in the external system databaseis CODE.

Choose the form Status so that the data fields are available for you to map.You need to monitor the Lookup form in order to catch its Open event, soyou must check “Monitor All Forms.” However, in the sample databasethere are other forms that are unrelated to the functioning of this applica-tion, exclude them by using a filter formula “FORM = “Status” ! “Lookup.”


Step 8. Perform the Final Steps1. Ensure that you have populated your external system source with the

leipackagetrack.nsf sample data as mentioned earlier. You can use aDirect Transfer activity to do this.

2. Enable (schedule) the Advanced RealTime activity you have created ifyou want to make it available for a specific interval of time, or click theStart! button on the Activity Document to make it active until you closeit manually.

3. Verify that the Activity is active by refreshing the view and watchingfor the Active icon. If the Error icon appears, you must go back andcheck your work.

4. From a Notes client create a Lookup document from the Actions menuand type in a tracking number in the PackageID field. Refer to theleipackagetrack.nsf database for example numbers.

5. Click the Locate button to save the Lookup document in the database.

The same document is reopened in the view. The selection formula inthe view then switches the form to Status when it sees that thedocument has been previously saved.


6. From a Web browser access the Lookup form using a URL similar tothis:

http://servername/leipackagetrack.nsf/Lookup?OpenForm

Note You will need to modify this to reflect the name of your ownDomino server and any other changes you might have made in thenames used in your application.

7. Type in a tracking number (PackageID field). Refer to theleipackagetrack.nsf database for example numbers.

8. Click the Locate button.

When you click the Locate button, the Lookup document is saved in thedatabase and the $$Return text is passed to the Domino HTTP process. Thenew document is reopened. The Advanced RealTime activity is activated,takes the value submitted to the Lookup form, and maps it to the AdvancedRealTime activity definitions and Status form. The PackageID value is thensent to the external system source and the table records are searchedaccording to the PackageID value. Results of the search are sent back to theWeb application as directed by the URL specified in the Lookup form.

Additional Advanced RealTime ExamplesThis section provides information about:

• Building a Virtual Fields or Virtual Documents activity that uses VirtualAttachments

• Using filter formulas, storage options, monitor orders, and storedprocedures in Virtual Fields activities

Building a Notes Application for a Virtual Fields or a VirtualDocuments Activity

The Notes application being monitored by a Virtual Fields or VirtualDocuments Activity must include data fields that map to data fields in theexternal data source.

In addition, the Virtual Fields Activity must include at least one field thatmaps to a key field in the external data source. A key field is one or morefields that are used to uniquely identify the data. A Virtual Fields Activitycan include multiple key fields.

The next section gives an example of an application that could be used witha Virtual Fields Activity or Virtual Documents Activity.


Example ApplicationShown below is a Notes application that monitors employee information inan external data source.

To see what the design view of this application looks like, see the followingsection.


Example of the Application Design ViewThe illustration below shows the design view of the example application. Inthis application there are labels next to the data fields. These data fieldsmap to the data fields in the external data source this application willmonitor. The Virtual Fields Activity or Virtual Documents Activity thatuses this application also defines the field mapping in the mapping area ofthe activity form.


Virtual Fields Activity ExampleShown below is an example of a Virtual Fields Activity that uses theexample application. The field mapping in the Mapping section of thedocument maps to the example application above.

Note You must initialize fields for the Virtual Fields Activity to populatethe Notes application you developed. Initialize fields by selecting “InitializeKeys” from within the Virtual Fields activity by opening the activity andclicking the “Initialize Keys” button.

Caution Initialize keys only one time. Initializing keys more than onceresults in duplicates.


Virtual Documents Activity ExampleFor Virtual Documents to work, you must add four additional fields to theexternal system database. These additional fields must be mapped to NotesID information fields. See “Required External System Fields for VirtualDocuments Activities” in the Virtual Documents Activities chapter forcomplete information.

Note You can use the Create Table Utility action button to create thesefields for you, however, see the Virtual Documents Activities chapter forcomplete details.

Below is an example of a Virtual Documents Activity that makes use of theexample application developed earlier in this chapter. The field mapping inthe Mapping section of the document maps to the fields in the exampleapplication.

Note In Virtual Documents there is no need to initialize keys. Initializationoccurs automatically.


Using Virtual AttachmentsThe Virtual Attachments feature allows you to use Notes to add attach-ments to the external system database. Once added, they can be accessedthrough the virtual views.

To use the Virtual Attachments feature, you must create a table and enterfields in the external system that accommodate Virtual Attachments. Thefields that you create at the external system must be in a table expresslycreated to hold these fields and these fields only.

Note You can use the Table Creation Utility button to automate thecreation of an attachment table. See “Using the Create Virtual AttachmentTable Option” in either the Virtual Fields Activity or Virtual DocumentsActivity chapters for complete information.

The required Virtual Attachment field names are as follows:

• EIDBID

• EIFILEID

• EIFILESIZE

• EINOTEID

• EIFILENAME

• EICONTENTS

Note The data types required for each of these fields vary according to theexternal system. See the following table:

imageblob(1048576)imagebytelong rawEICONTENTS

varchar(255)varchar(255)varchar(255)varchar(255)varchar2(255)EIFILENAME

intintegerintintnumber(10)EINOTEID (d)

intintegerint int number(8)EIFILESIZE (c)

intintegerintintnumberEIDBID**

char(32)character(16)char(16)char(16)Varchar2(16)or char(16)

SQL ServerDB2 (b)Sybase (a)InformixOracle

External System Data Types Attachment TableFields


a) In Sybase, column names must be in upper case, for example, EINOTEID.




d) EINOTEID is a DWORD, or an unsigned 32-bit integer. According to theformula 2^n - 1, this gives a maximum EINOTEID of 4,294,967,295 whichrequires 10 digits.

You identify the table where these fields reside by entering the name of thetable in the “Attachment table” field in the activity form. In the illustrationbelow the table that is to be used for attachments is called MY_ATTACH.

Note Any attachments that were not entered into the external systemthrough the Virtual Attachment process will not be accessible througheither Virtual Fields or Virtual Documents. That is, if you addedattachments to the external system database through another process, forexample, SQL commands, you cannot access then through Virtual Fields orVirtual Documents. Of course, you can create the table using SQLcommands.


Using Virtual Fields OptionsThis section provides examples of using filter formulas, storage options,monitor orders, and stored procedures in Virtual Fields activities.

Using Filter FormulasThis section provides examples of how you would use the Filter Formulaoption in conjunction with the Monitor Order option to achieve specificresults.

Saving Data to an External Data SystemScenario: You want to store data from a Notes document in an externaldata system, such as a DB2 or Oracle database, when the document databecomes stable.

When each document is stable and ready to store on the external system,you would change its status from “under review” to “publish.”

How to Configure: In this case, you would set up a Virtual Fields Activitythat monitors the Notes application.

In the Virtual Fields Activity, you would use a filter formula that includesonly documents that have been marked “Published.”

At that point the information from the Notes document will be written tothe DB2 database, where it would be available to other applications. Anydocuments that are still “under review” will not be stored in DB2.

Accessing Different External Sources using the Same NotesApplicationScenario 1: You want to use a single Notes front end to interact with infor-mation that is potentially in two different tables. For example, the NorthEast sales information is in a different table than the South West region.

In this case, you would set up one Virtual Fields Activity for each regionwith different external data sources, but using one Notes document as thefront end.

You could use a filter formula that would detect the region ofinformation/account request and go to the appropriate external sourcedata.

Scenario 2: Suppose that you have two product catalogs in differentdatabases, but want to present the data using the same front end Notesapplication. You want to use a single Notes front end, but dependent on afield, you want to control where the data is coming from.


Set up identical Virtual Fields Activities monitoring a single Notes applica-tion, but have each Virtual Fields Activity use a filter formula to handle partof the request.

Using Data Storage OptionsThis section provides some examples of how and when you would use theData Storage options in Virtual Fields Activities.

Building ViewsAny data that you want to use when building views must reside in theNotes document. Use the option “Leave Selected real-time Fields inDocument.” When you select this option, you can choose the fields that youwant to reference in a view from the list of available fields.

Storing a Static Copy of External DataIf you want to store a static copy of the external data, select “Leave All real-time Fields in Document.” Note that if the external source data changes, thedata in the document is not updated until the document is reopened.

Using the Monitor Orders OptionIn this scenario, the external data for your Notes Human Resources Infor-mation system is in multiple tables. A “join” of the data is required to tiethese various tables together to populate the single Employee Informationform in the Notes application. In some cases, a join from the database maynot be possible, because the tables may reside in different databases (one inOracle, one in Sybase, for example). Information in the Employee Informa-tion form includes Employee Name, Department Name and Location Infor-mation. The following table explains which fields are used from which tableand how they will relate to the Notes form.

Fields Used:

continued

DeptNameDepartment

DeptNoDeptNoDepartmentNo (may be hidden)

EmployeeNameEmpName

EmployeeIDEmpID

LOCATION Table(access with monitororder 3)

DEPARTMENT Table(access with monitororder 2)

EMPLOYEETable

EmployeeInformation Form


LocName

…

Location

LocCodeDeptLocDepartmentLoc(may be hidden)

LOCATION Table(access with monitororder 3)

DEPARTMENT Table(access with monitororder 2)

EMPLOYEETable

EmployeeInformation Form

To do this join, you will create three Virtual Fields Activities that eachmonitor separate tables: one to monitor the Employee table, one to monitorthe Department Table and one to monitor the Location Table. The firstActivity (using a Monitor Order of 1) will provide data that will be used bythe other Activities (with Monitor Orders of 2 and 3) as “keys” to theirtables. The Notes Form “Employee Information” will need to contain thosefields that will act as “keys” to the secondary tables. These fields may be“hidden” from the user. If you expect updates to be made through theNotes application to these secondary tables, select the Option “Leaveselected real-time fields in Documents” and list all the fields which are usedas keys to the external source (DeptmentNo, DepartmentLoc).

Note Activities with monitor orders of 2, 3, 4, and so on, must monitor anOpen event. They may monitor other events too, but one of the events mustbe an Open event. Depending on the nature of the activity, the activity withmonitor order 1 may be required to monitor an Open event as well.

1. Create a connection document for each of the external data sources: onefor the employee table, one for the department table, one for thelocation table.

2. Create a Virtual Fields Activity based on the Employee InformationForm and the Employee Table. Select all fields that will be used by theform and/or used as a key to another field. In this case, select at leastthe following: EmployeeName, DepartmentNo.

DeptNoDepartmentNo

EmployeeID as the keyEmpID as the key

Employee TableNotes


3. Create a second Virtual Fields Activity based on the EmployeeInformation Form and the Department Table. Select the followingfields:

DeptName

Set the Monitor Order for this activity to 2. This willallow the first activity to retrieve the information fromthe employee table before looking into the departmenttable for the DeptName field.

Department

Deptno as the keyDepartmentNo asthe key

Department TableNotes

4. The third activity will work like the second, except it monitors theLocation Table. It will use a monitor order of 3 because its lookupdepends on information provided by the second Activity.

LocNameLocation

LocCode as the keyDepartmentLoc as the key

Location TableNotes

Using Stored Procedures in Sybase/SQLThis section provides an example of a Virtual Fields Activity that usesstored procedures with a Sybase external data source or a SQL (usingSybase) external data source.

In this example there are four stored procedures for the table addrbook inSybase. When using these stored procedures, the key fields used must beFirstName then LastName and the mapped fields must be (MailDomain,MailServer, MailAddress, CompanyName, and State). The stored proce-dures, table name and fields must use the correct case since Sybase is casesensitive.

To use a stored procedure, enter the name of the stored procedure in theoptions section for the appropriate event in the Virtual Fields Activitydocument. In this example, these would be:

Create: QEInsertaddrbook

Open: QESelectaddrbook

Update: QEUpdateaddrbook

Delete: QEDeleteaddrbook


Below is an illustration of a Virtual Fields Activity document showing howthese stored procedures are entered in the Stored Procedure fields of thecorresponding document event options. Following the illustration is anexample of how you can test the stored procedures directly in SQL throughthe database client.


Testing the Stored Procedures in SQLThe examples below show how you would execute the stored procedures inSQL through the database client, in this case Sybase. You can test that thestored procedures work properly by executing them directly as shownbelow.

Note This example assumes that the table “addrbook” exists with thecolumns shown.

execute QEInsertaddrbook ’OurDomain’, ’ThisServer’, ’OurAddress’, ’OpenResearch’, ’NH’, ‘Adelino’, ’Fontes’

execute QESelectaddrbook ‘Adelino’, ’Fontes’

execute QEUpdateaddrbook ’OurDomain’, ’ThisServer’, ’OurAddress’,’Open Research’, ’NH’, ‘Adelino’, ’Fontes’

execute QEDeleteaddrbook ‘Adelino’,’Fontes’

Stored Procedure DefinitionsBelow are the actual stored procedure definitions used in the precedingexample. Note that these are Sybase procedures; stored procedures forother data sources may be different.

create procedure dbo.QEInsertaddrbook(

@FirstName varchar(20),

@LastName varchar(20),

@MailDomain varchar(20),

@MailServer varchar(20),

@MailAddress varchar(20),

@CompanyName varchar(20),

@State varchar(20)

)

as

INSERT INTO addrbook

(FirstName,LastName,

MailDomain, MailServer,

MailAddress, CompanyName,State)

VALUES

(@FirstName, @LastName,


@MailDomain, @MailServer,

@MailAddress, @CompanyName, @State)

create procedure dbo.QESelectaddrbook(


@LastName varchar(20)

)

as

select FirstName,LastName,

MailDomain, MailServer, MailAddress,

CompanyName,State from addrbook

WHERE FirstName = @FirstName and

LastName = @LastName

create procedure dbo.QEUpdateaddrbook(


@LastName varchar(20),

@MailDomain varchar(20),

@MailServer varchar(20),

@MailAddress varchar(20),

@CompanyName varchar(20),

@State varchar(20)

)

as

UPDATE addrbook SET

MailDomain=@MailDomain, MailServer=@MailServer,

MailAddress=@MailAddress,

CompanyName=@CompanyName, State=@State

WHERE

FirstName=@FirstName and LastName=@LastName

create procedure dbo.QEDeleteaddrbook(



@LastName varchar(20)

)

as

DELETE FROM addrbook

WHERE FirstName=@FirstName and LastName=@LastName

Using a DB2 Stored ProcedureIn DB2 the parameter types are interpolated from the Notes datatypes. Forexample, if the Notes key field is a number, the DB2 parameter type will beDOUBLE. Your stored procedure should account for possible differences ininput types (or it should at least check the input type).

Model your stored procedure on the following example.

/* Stored procedure Example */

#include <memory.h>

#include <string.h>

#include <c:\sqllib\include\sql.h>

#include <c:\sqllib\include\sqlda.h>

SQL_API_RC SQL_API_FN sf_proc (void *reserved1,

void *reserved2,

struct sqlda *inout_sqlda,

struct sqlca *ca)

{

/* Declare a local SQLCA */

EXEC SQL INCLUDE SQLCA;

/* Declare Host Variables */

EXEC SQL BEGIN DECLARE SECTION;

char *select_stmt = "SELECT NUMBER2, TEXT1, TEXT2, MODIFIED,NUMBER1 FROM SIMPLE WHERE NUMBER1 = ?";

long int number1;

EXEC SQL END DECLARE SECTION;


if (inout_sqlda)

{

if ((inout_sqlda->sqlvar[0].sqltype == SQL_TYP_INTEGER) ||

(inout_sqlda->sqlvar[0].sqltype == SQL_TYP_NINTEGER))

number1 = *((long int *) (inout_sqlda->sqlvar[0].sqldata));

else if ((inout_sqlda->sqlvar[0].sqltype == SQL_TYP_FLOAT) ||

(inout_sqlda->sqlvar[0].sqltype == SQL_TYP_NFLOAT))

number1 = (long int) *((double *) (inout_sqlda->sqlvar[0].sqldata));

else

number1 = 0;

EXEC SQL WHENEVER SQLERROR GOTO ext;

EXEC SQL PREPARE stmt FROM :select_stmt;

exec sql DECLARE curs CURSOR FOR stmt;

exec sql OPEN curs using :number1;

}

ext:

memcpy(ca, &sqlca, sizeof(struct sqlca));

if (inout_sqlda)

*(inout_sqlda->sqlvar[0].sqlind) = -128;

return(SQLZ_DISCONNECT_PROC);

}


Using an Oracle Stored ProcedureAn Oracle stored procedure can be used in a Virtual Fields Activity or withan LC LSX script. However, the stored procedure being called must have itsparameters configured correctly for the call.

When you browse for a stored procedure in the Connection Document, adialog box appears, listing all the stored procedures in the external systemdatabase. When you choose a stored procedure, the parameters of thechosen stored procedure are automatically listed in the ConnectionDocument. If you do not specify a stored procedure in the ConnectionDocument, you can select a stored procedure and its associated parametersfrom the Virtual Fields Activity Document. In either case, the stored proce-dure is entered as the default stored procedure in the Activity events in thestored procedure field, followed by its list of parameters. In most cases,returned values are handled by the external system database. In the case ofOracle, the Lotus Connector for Oracle 7 or 8 handles returned information.This is transparent to you, however the person responsible for writingOracle stored procedures should be aware of it.

Input Values and Named ParametersInput values are provided to Oracle procedures as named parameters. Thisrequires that the parameters in Oracle use the same names as the fieldsbeing provided as input values. The inputs being provided include keyvalues when they are used in the context of a keyed operation (selection,update, or delete context), and data values when relevant (insert or deletecontext). The input value data types provided by the Lotus connection areselected as the closest match to the LEI data type and are converted byOracle to the procedure parameter-defined data types, provided that theconversion is supported by Oracle.

Using Output Parameters to Return ResultsOracle differs from other RDBMS Connectors in that there is no way toreturn a result set from a procedure. Therefore, the Lotus Connector forOracle 7 or 8 supports output parameters as a way of returning results froma stored procedure. This requires additional information to be available atthe time the procedure is called, specifically the context of the call and theoutput parameter names. This information will be automatically providedby Virtual Fields activities, but must be manually specified when callingOracle procedures from an LC LSX script. The context indicates whether theprocedure should expect and specify output parameters, and the parameternames are provided as a property of the procedure call request to theOracle connection. The output parameters must be standard data types —row sets may not be returned. This restricts the result set from an Oracleprocedure to a single row. Any parameters that are indicated as input


parameters and are also in the output parameter list will be provided asinput/output parameters.

Example of an Oracle Stored ProcedureThe following is an example of an Oracle stored procedure body. This is theformat that would be required for the Open event of a Virtual Fields Notesactivity assuming that the key field is called NUMBER1 and the data fieldsare called NUMBER2, TEXT1, and TEXT2. In this context, the key field isthe input parameter, and the result set is expected to include the data fieldsand the key field. To accommodate the fact that one of the output parame-ter names is the same as a key value in the select statement, the parameterkeys should be copied to local variables to avoid scoping problems in theprocedure.

(NUMBER2 out tablename.number2%TYPE,

TEXT1 out tablename.text1%TYPE,

TEXT2 out tablename.text2%TYPE,

NUMBER1 in out tablename.number1%TYPE)

IS

BEGIN

DECLARE number1_request tablename.number1%TYPE := number1;

BEGIN

SELECT t.NUMBER2, t.TEXT1, t.TEXT2, t.NUMBER1

INTO number2, text1, text2, number1

FROM tablename t

WHERE t.NUMBER1 = number1_request;

END;

END;


Appendix D Using Virtual Fields with Virtual Documents

This appendix provides information about using Virtual Fields and VirtualDocuments activities. It is assumed that you are familiar with these twoactivity types.

IntroductionThis appendix builds on content introduced earlier in this guide in theVirtual Documents and Virtual Fields chapters. See those two chapters formore detail on these two related activities.

A Virtual Document is essentially equivalent to a native Notes document inevery way, except that it is not stored in an NSF and all its data is externalto the NSF, as a result you can add Virtual Fields to the Virtual Document.You do this by simply creating a Virtual Fields activity that monitors thesame form that a Virtual Documents activity monitors. This effectively addsvirtual fields to a document that is itself already virtual.

The concept may seem odd at first, but the ability to layer virtual fields overa virtual document adds significant extensibility and functionality not avail-able to Virtual Documents alone. It also adds a level of complexity, withpotential pitfalls, that needs to be considered before using this functionalityin this manner. The user must be aware of his or her needs and whether thisapproach is suitable to solve a particular problem, or whether it can besolved more simply by using only Virtual Fields or only Virtual Documents.This section is intended to help you answer this question and it describeshow to properly implement this advanced solution.

377

Advantages to Using Virtual Fields with Virtual DocumentsThere are two potential advantages to adding Virtual Fields to a VirtualDocument.

• The ability to include data from other external data sources, potentiallyfrom entirely different external data source systems, into a VirtualDocument.

• The ability to utilize some of the functionality from Virtual Fieldsactivities, which is inherently not available in Virtual Documentsactivities, within in a Virtual Document.

It very important to understand that a Virtual Document stands on its own,and that, by definition, all its fields are virtual. These are the fields whichare mapped in the Virtual Documents activity. A Virtual Documents activ-ity monitors a single Notes Form, and all the mapped fields in that form aresaid to be virtualized and exist in a single table. Consequently, each tablerow corresponds to single Virtual Document. In addition, all the othervarious elements which comprise a Notes document are also virtualized ina external data source table, and hence the entire document is said to bevirtual.

In essence, a Virtual Documents activity instantiates a complete Notesdocument, all of whose components and data exist external to the DominoNSF. This is the fundamental difference between Virtual Documents activi-ties and Virtual Fields activities. While Virtual Documents virtualizes theentire document, Virtual Fields virtualizes individual fields and utilizes keydocuments stored in the NSF to hold the document level information andthe all important key fields used to map a document to a particular externaldata source table row.

Virtual Documents removes the need to have and maintain stub documents,but at the expense of not being able to map various fields within a singledocument to different external data sources, nor can you have some fieldsstored natively (not virtual). Said another way, the document level natureof Virtual Documents means that all the fields in a Virtual Documentalways map to a single external data table row which describes thedocument as a whole; by contrast, multiple Virtual Fields activities cansupply external data from multiple external sources to various virtual fieldswithin a single document. The result of using a Virtual Fields activity tomonitor the same form as a Virtual Documents activity is to add virtualfields to the virtual fields that are inherently part of the virtual documentitself. If Virtual Field activity maps its fields from some other supported


external system, you’ve essentially added the ability to create a VirtualDocument that accesses data from multiple external systems, which issomething you cannot do with Virtual Documents alone.

What Happens to the Virtual Field Key DocumentsYou may wonder how you can use Virtual Fields if you haven’t created anykey documents to supply keys. The short answer is that you do have keydocuments. The key documents are now actually the Virtual Documentsthemselves. This will be discussed in more detail later, but the primaryrequirement is that one or more fields in the Virtual Document (mapped bythe Virtual Documents activity) can be used as key(s) for the Virtual Fieldsactivity. It is not necessarily advantageous to think of Virtual Documents asstrictly a substitute for Virtual Fields key documents, or as a way to useVirtual Fields without the need for maintaining and synchronizing nativestub documents. The fact that the key documents are now virtual does notalleviate these issues, and in some ways adds more overhead. Think ofVirtual Fields as a way to extend the external data access capabilities of VirtualDocuments to include data from multiple external sources and to add some extrafunctionality. Thought of correctly, Virtual Fields adds power to VirtualDocuments, rather than Virtual Documents makes Virtual Fields easier touse.

Appendix D: Using Virtual Fields with Virtual Documents 379

Additional FunctionalitySome Virtual Field functionality can be incorporated into VirtualDocuments by configuring one or more Virtual Fields activities to monitorthe same form as a Virtual Documents activity. Most notable of these is theability to use multivalue data fields within a Virtual Document; fieldsmapped by the Virtual Documents activity cannot be multivalue fields. Anymultivalue fields in a form monitored by a Virtual Documents activitywould instead be mapped by a Virtual Fields activity with the appropriatemultivalue parameters set. When viewing a Virtual Document, the fieldsmapped with the Virtual Documents activity will appear together with themultivalue fields, and any other fields, mapped by the Virtual Fieldsactivity.

Virtual Fields also has the notion of monitor order, whereby multipleVirtual Fields activities monitoring the same form can be set up to “run” ina specific order. In a typical case, the first Virtual Field activity using akey(s) supplied from the “key document”, populates a set of virtual fieldsin the document. The populated virtual fields from the first activity thensupplies the key(s) for the next Virtual Field activity in the monitor orderand so on. In some circumstances this ability to sequence activities can bevery useful, but it is not possible with Virtual Documents alone since asingle Virtual Documents activity exists in a given form. By adding two ormore Virtual Fields activities to Virtual Documents, the fields mapped bythe first Virtual Fields monitor can supply the key(s) for the second activityand so on as before. The only difference is that the Virtual Documentsupplies the key(s) for the first Virtual Fields monitor. In the context ofmonitor order processing, you can think of the Virtual Documents activityas always having a monitor order of 0; that is, it always runs first.

Adding Virtual Fields to Virtual DocumentsAdding virtual fields to a virtual document is somewhat of a misnomersince the fields mapped by the Virtual Document activity are of coursealready virtual. What we are really doing here is adding more virtual fieldsmapped in one or more Virtual Fields activities. This is simply accom-plished by creating a Virtual Fields activity that monitors the same Notesform which is being monitored by a Virtual Documents activity. It’sassumed that you are already familiar with the creation of VirtualDocuments and Virtual Fields activities.


The most important aspect of creating the Virtual Fields activity involvesthe selection of the key field(s). Just as ‘regular’ Virtual Fields activitiesrequire that the key fields exist in the key documents, the key field(s) heremust be also be mapped by the Virtual Documents activity. Because thekey(s) are mapped by both activities they must be common to both externalsystem tables. Since Virtual Documents activities do not have a notion ofkey(s), they will appear as any other data field in the Virtual Documentmapping section, but they will then be mapped as keys in the Virtual Fieldsactivity. (see figure).

In the example [shown in the above figure], empno is mapped as a datafield in the Virtual Documents activity along with some other employeeinformation. All these fields map to the external system employee informa-tion table. The Virtual Fields activity maps the same empno field to anotherexternal system table, along with some other data relating to the employee’sdepartment. The empno field is the only field that need be in commonbetween the two tables and the corresponding activity mapping. Whenthese activities are running, the Virtual Documents activity will firstconstruct the Virtual Document which will essentially provide the neededkey(s) for the Virtual Fields activity to be able to access its external systemtable. The end result is a Notes Document which is a composite virtual


document; that is, it contains virtual fields supplied by both the VirtualDocuments activity and the Virtual Fields activity using data from twodifferent external system tables.

This example can be extended further to include one or more additionalVirtual Fields activities. These activities could use the same empno field asthe key, or use other fields as keys, possibly supplied by other Virtual Fieldsactivities and using the Virtual Fields monitor order capability. Refer to theVirtual Fields activity chapter for more information about monitor order.

With some caveats, almost anything that can be done with regular VirtualFields activities using key documents can be done with Virtual Fields andVirtual Documents together. The next sections will cover some of thespecial issues which arise when using these two types of activity together.

Managing the Key Field Under Different ScenariosAs implied earlier, all the Virtual Fields activity key(s) which exist in theVirtual Documents table must also exist in the Virtual Fields table, or elseaccessing the virtual document will fail because the lookup on the VirtualFields table will fail. In other words, attempting to open a virtual documentthat contains a key value that does not exist in the Virtual Fields tableresults in an Notes open failure. Under normal circumstances this shouldnot happen, but certain improper configurations and/or error conditionscould lead to this situation.


Scenario 1: One-to-Many Record CorrespondenceThis situation arises when there is not a strict one-to-one correspondencebetween the records in the Virtual Documents table and the Virtual Fieldstable. This could be described as a one-to-many record correspondence.

For example, suppose an external system table contains employee data for100 employees. This table can easily be virtualized into a Domino environ-ment through a Virtual Documents activity in the usual manner. One of thecolumns in this table provides a department code indicating the departmentto which employee is currently assigned. Now suppose a second externaltable contains department data for each of the company’s 12 departments,using the department code as a unique key. Each department has one ormore employees assigned to it; this is the one-to-many relationship. Thegoal is to consolidate employee information with information about theemployee’s current department on a single Notes form. This would makethe consolidated document appear as a single Notes document which canbe manipulated in exactly the same ways a normal Notes document can bemanipulated in a Domino environment.

As described earlier, the only way to supply these additional virtual fields(department data) to your virtual document (employee data) is by using aVirtual Fields activity which monitors the same Notes form as the VirtualDocuments activity, and mapping the department code field as the key inthe Virtual Fields activity.

However, if the Virtual Fields activity is monitoring ALL Notes events,including creates, updates and deletes, a problem will arise when anemployee is terminated, or transferred to another department, or a newemployee is hired. Consider the following cases:

If an employee Fred Waters in department 4 is terminated, and the Notesapplication is intended to only contain information about active employees,simply deleting Fred’s document has the following consequences:

1. Fred’s record in the Virtual Documents table will be marked as deleted;this allows Domino to replicate the document deletion to other potentialdatabase replicas.

2. Since the Virtual Fields activity is monitoring delete events, it willdelete Fred’s former department record from the Virtual Fieldsdepartment data table, using 4 as the key.

3. All of Fred’s former co-worker’s records in department 4 will no longerbe accessible through Notes, since opening the virtual document willresult in a Virtual Fields lookup failure for their department data.


If Fred is transferred from department 4 to department 7, updating Fred’sdocument has the following consequences, but only if key field updates areallowed in the Virtual Fields activity (they are BLOCKED by default):

1. Fred’s department code in the Virtual Documents employeeinformation table will be updated from 4 to 7

2. Since the Virtual Fields activity is monitoring update events, thedepartment code record in the Virtual Fields department informationtable will also be updated from 4 to 7, assuming the Virtual Fieldsactivity is set to allow key field updates.

3. Updating the key field with a new value will probably have manynegative consequences, ranging from document access problems forother employees still in department 4 to duplicate key errors from theexternal system table.

If Bob Smith is hired as a new employee to help Fred out in department 4,the following will occur:

1. Bob Smith’s record will be inserted into the Virtual Documents table,with 4 as his department code.

2. Since the Virtual Fields activity is monitoring create events, a new rowfor department 4 will be created in the Virtual Fields departmentinformation table.

3. This may lead to duplicate key problems since there is already adepartment 4, and it really doesn’t make sense since we do not want toreenter department information for department 4, but instead want toadd a new employee who will work in department 4.

SolutionWhat we really want to do in this scenario is to make the Virtual Fieldsactivity a Read Only activity that simply uses the department informationtable as a lookup table to provide department information when eachemployee’s documents is opened. This is very easily accomplished byalways setting the Virtual Fields activity to only monitor OPEN eventswhen you have this one-to-many scenario. Set up this way, deletions andupdates to an employees document will only affect the employee record inthe Virtual Documents employee table. Creating a new employee recordwill simply involve entering the employee information including thedepartment code. When the new employee’s record is subsequentlyopened, the correct department information will be displayed along sidethe employee information.


A special case arises if you do want to be able to update department infor-mation from within an employee’s virtual document. In this situation, allowthe Virtual Fields activity to monitor update events, but be sure that theupdate event option for Key Field Updates is set to Block (which is thedefault). This will allow you to edit department information, but still allowyou to transfer an employee to a different department without running intothe problem described above, where the department code key is changed inthe department information table as part of the update.

If you are already familiar with the ‘regular’ use of Virtual Fields activities,you may recognize this one-to-many scenario. This typically occurs whenusing multiple Virtual Fields activities with a prescribed monitor order. Inthis scenario. the first Virtual Fields activity in the monitor order providesthe key for second Virtual Fields activity which accesses a read only typelookup table such as the department information table described above. Thesame problems and solutions described above apply in this case. The onlydifference in the virtual documents context is that the Virtual Documentsactivity essentially plays the role of the first activity by providing the keyfor the Virtual Fields activity.

Scenario 2: One-to-One Record CorrespondenceThere may be circumstances where it is desirable to have read/write accessto the Virtual Fields table. This would include the case where there is aone-to-one relationship between the records in the two tables. For example,instead of department information in the Virtual Fields table, suppose thetable simply included more employee specific information concerning jobperformance. The key might be the employee’s social security number. Inthis case, when an employee is terminated and the document deleted fromthe Notes application, it may be preferable to delete all the employeesrecords from both tables. Also, being able to update information about theemployee, including job performance data in the Virtual Fields table, maybe desirable. Similarly, a new employee would always result in new recordsbeing created in both tables.

In this situation you do have a one-to-one relationship between the twotables, as a result, you may not want to block key field updates, becauseunlike the example where the key was a department code shared by multi-ple employees, here the key uniquely identifies a single employee. In ourexample, if an incorrect social security number is changed but the key fieldupdate is blocked in the Virtual Fields activity, a subsequent attempt toopen the employees record will fail because the lookup into the VirtualFields table will now fail since the key was not affected by the update.


Key InitializationThe concept and process of initializing keys with Virtual Fields activitiesusually involves the creation of “key documents” which are native Notesdocuments stored in the Notes database. They typically only contain keyfield data used by the Virtual Fields activity to access the correspondingexternal system table row, so there is one key document created for eachrow in the table. When using Virtual Fields with Virtual Documents activi-ties to produce a composite document as described in the above precedingsections, the notion of key initialization is somewhat inconsistent with theintended functionality. It is usually assumed that the external table to beused with the Virtual Documents activity has already been “virtualized”.See the Virtual Documents chapter for details on external system tablevirtualization. In this case, the documents which will play the roll of keydocuments for the Virtual Fields activity already exist. The addition ofvirtual fields through the Virtual Fields activity simply requires a commonkey field and table column as described in earlier examples. As you can see,in this scenario there are simply no keys to initialize since the virtualdocuments already exist.

Because of the transparency of Virtual Documents, it is possible to use thetraditional Virtual Fields key initialization in conjunction with VirtualDocuments. Assuming that both activities have been set up to monitor thesame Notes form and have a common field to act as a key for the VirtualFields activity, starting the Key Initialization process in the Virtual Fieldsactivity will essentially create virtual key documents. As with ‘normal’ keyinitialization, one virtual key document will be created for each row in theVirtual Fields table. Of course, each new virtual key document will in turncorrespond to a newly created row in the Virtual Documents table. Thattable must have as a minimum one column for each key used by the VirtualFields activity.

Note The Virtual Documents activity must be running during the keyinitialization, or else traditional non-virtual documents will be created.

This above technique illustrates the flexibility of using Virtual Documents.With this method, you can use an existing table used by a Virtual Fieldsactivity to essentially populate another table mapped to a VirtualDocuments activity and thus creating virtual key documents. However, asdiscussed earlier in this chapter, using virtual documents solely as a way toremove native key documents is not necessarily a good idea, unless it isvital to keep the size of an NSF at a minimum and to keep all data externalto the Notes database. However, if this is the intent, a better solution wouldbe to remove the Virtual Fields activity from the picture all together, andjust virtualize the existing Virtual Fields table using only VirtualDocuments activity to monitor the Notes form.


Automatic Background Virtualization and Key Synchronization ProblemsVirtualization is the process used by a Virtual Documents activity to adaptan external system table in such a way as to make each row represent aNotes Document. This occurs automatically and immediately when creatinga new virtual document through a Notes client . The corresponding row isinserted into the external table when the document is saved. Virtualizationcan also be done automatically by a background process which scans theexternal table for existing rows that have not been virtualized as Notesdocuments, and thereby makes them accessible through Domino. Thisfeature is useful when the external data table already contains data and you want to make the data automatically accessible through Domino. Theexternal data source table is also periodically scanned for rows that may beadded through a non-Notes client or process and needs to be virtualizedinto the NSF. See the Virtual Documents activities chapter for more details.

If a Virtual Fields activity is also monitoring the same form, virtualizationdoes not have a direct impact on the Virtual Fields activity or the externaltable associated with it. However, as described earlier, virtual documentmust be a common data field in the Virtual Documents activity that alsoserves as the key for the Virtual Fields activity. If an external table is virtualized and it contains rows with key values that do not exist in theVirtual Fields table, an error will occur when trying to subsequently accessthe virtual document because the lookup on the Virtual Fields table hasfailed. If the problem is simply with incorrect key data, leave the VirtualDocuments activity running but shut down the Virtual Fields activity. Youwill then be able to either delete the offending virtual documents or openand update the virtual documents with the correct key data, then restart theVirtual Field activity. Conversely, if the problem is with incorrect key datain the Virtual Fields table, you will have to manually update (for example,through a SQL client) the external data source table with the correct keydata, or add the necessary rows, to match the data in the Virtual Documentstable.

If you have a situation where some of the records in the Virtual Documentstable simply do not have applicable data in the Virtual Fields table you mayneed to make special provisions. For example, the Virtual Documents tablecontains all company employee data, and the employee’s department codeis used as a key to lookup department information in the Virtual Fieldstable. However, some employees are independent contributors and don’thave a department number (it’s NULL in the Virtual Documents table). Thiswill clearly cause a problem when accessing this document since the lookupon Virtual Fields table will fail.


Again, it is important to choose a data value(s) in the Virtual Documentstable that can always serve as a unique key(s) for the Virtual Fields table.An easy fix for this example might be to simply add a row to the depart-ment information table (Virtual Fields table) which has a special depart-ment number key (0 for example), with all other department information setto null. Then assign the special department number to each of the applica-ble employee records in the employee information table (Virtual Documentstable). Another more sophisticated approach could be to simply use a postopen formula for the Virtual Documents activity which always sets thedepartment number field to 0 if it is null when opening the virtualdocument.

As mentioned above, when creating a virtual document through a Notesclient, the corresponding external row will be automatically inserted andvirtualized into the external table by the Virtual Documents activity whenthe document is saved. A new row will also be inserted into the VirtualFields table for the fields mapped by the Virtual Fields activity if it ismonitoring create events. Since the two operations occur together, thereshould be no synchronization issues. If the Virtual Fields activity is notmonitoring create events, it is assumed that the entered key already exist inthe Virtual Fields table.

Error Conditions and Key Field Synchronization ProblemsAssuming the external table used by the Virtual Documents activity and thetable(s) used by the Virtual Fields activity(s) are initially synchronized;every row in the Virtual Documents table contains a valid unique key(s) forthe Virtual Fields table, problems can arise when certain error conditionsare encountered. However, problems will occur only when the VirtualFields activity is monitoring any of the events, which include Create,Update, and Delete events. Depending on your particular write application,you may or may not be using the Virtual Field activity(s) in a read/writefashion. If you are using the Virtual Fields activity in a read-only fashion byonly monitoring the Open event, the error conditions discussed in thissection are not applicable. See the section “Managing the Key Field UnderDifferent Scenarios” for more information.

When creating or updating a document, if an error occurs inserting orupdating a record into the Virtual Fields or Virtual Documents table, thedocument is not created and an error message is returned.

For example, if connectivity is lost between Domino and the external systemfor the Virtual Fields table, a connectivity error will be provided in a dialogbox and the error will be logged in the Virtual Fields activity log. TheVirtual Document activity processing will not occur and no records will be


inserted/updated in the Virtual Document table. All Virtual Fields activityprocessing is performed before Virtual Document activity processing wheninserting, updating , or deleting virtual documents. Again, this can onlyoccur if the Virtual Fields activity is monitoring one or more of these events.

A problem may occur if an error occurs in the Virtual Document processing,which always occurs after all Virtual Fields activity(s) processing isfinished. The result of this is that the Virtual Field table may be updated, ora new row inserted, or a row deleted, depending on the event. However,the corresponding operation fails on the Virtual Documents table, perhapsdue to a similar connectivity issue as in the earlier example. At this timethere is no rollback on the Virtual Fields table operation. The followingdescribes how to handle this situation, and assumes a single Virtual Fieldstable with a single key.

1. If creating a new document the Virtual Fields table will contain a newrow. When the error condition is resolved, an attempt to create thedocument may still fail because the Virtual Fields activity will try toreinsert the row with the same key that already exists, resulting in aduplicate key error. To resolve this problem, first delete the new row inthe Virtual Fields table or shut down the Virtual Fields activity, prior toattempting to create the document again. After, restart the VirtualFields activity if you shut it down.

2. If updating a document the problems are similar to creating a newdocument. The Virtual Fields activity will first update its table with anymodified data. A synchronization problem arises only when key fieldupdates are allowed by the Virtual Fields activity (they are blocked bydefault), and an error occurs in updating the Virtual Documents rowwith the new key value. A subsequent attempt to open the VirtualDocument will fail because it will try to access the Virtual Fields tablewith what is now a nonexistent key, because it has already beenchanged in the Virtual Fields table but not in the Virtual Documentstable. To rectify this situation, shut down only the Virtual Fieldsactivity, open the document and update the key value field with thecorrect key, then save and close the document Restart the Virtual Fieldsactivity and reopen the document you should now see all the correctdata.

3. If deleting a document the Virtual Fields activity will delete thecorresponding row in the Virtual Fields table. When the error conditionis resolved, you will be able to successfully delete the document and noerror will be reported as a result of the Virtual Fields table row alreadybeing deleted. However, an attempt to open the document after theinitial error has occurred will result in an error, since the Virtual Fieldsrecord has already been deleted so the lookup on that record will fail.


Non-Key Data FieldsNow that the perils of the Virtual Field key field(s) and how to set up theactivities with special regards to the key(s) has been explained, how shouldother non-key data fields be handled? As discussed the only fields thatmust be mapped in both activities are the fields which will act as the key(s)for the Virtual Field Activity(s). Of course this means these fields must havecorresponding columns in both the Virtual Fields and Virtual Documentstables. Beyond this, no other fields need to be mapped in both activities.Whether or not other data fields need to mapped depends solely on yourparticular application and how the external system tables are set up andused.

Using an earlier example where the employee information was stored in avirtualized Virtual Documents table, and look-ups were used into a VirtualFields table to access the employee’s department information, this wouldillustrate a case where there would typically be no shared data between thetwo tables, except for the department code key. The department code keyfield would be mapped by both activities.

Considering the example where the Virtual Fields table contains jobperformance data for a particular employee, using a unique employee id(for example, social security number) as the key, you might have a differentsituation since you now have the previously discussed one-to-one relation-ship between records in the two tables. As such, there might be duplicatedinformation between the two tables. For example, the employee’s full nameand telephone number might be included in both tables. If this information,say the phone number, needs to be updated but it is only mapped by oneactivity, only that activity’s table will be updated, and unexpected resultsmay occur. For example, if the phone number is updated but the phonenumber field is only mapped by the Virtual Documents activity only theVirtual Documents table will be updated. The Virtual Fields table will notbe updated with the new number. From the perspective of the Notes appli-cation this does not pose a problem since the unmapped phone numbercolumn in the Virtual Fields table will never be accessed. However, youmay have some other external application which depends on all the infor-mation in the table being used by the Virtual Fields activity to be correctand up to date. As a general rule of thumb, any common data columnwhich is mapped in one activity should also be mapped by the other activ-ity unless the field is a read only field.

Be aware that any PRE or POST-event formulas which are run in one activ-ity will not automatically apply to another activity. For example, if apre-update formula is run to always validate and pre-pend an area code tothe phone number field in the Virtual Fields activity, it will have to beduplicated in the Virtual Documents activity to achieve the same results.


Virtual Fields Data Storage OptionThe purpose of this option for ‘regular’ Virtual Fields activities is to simplyallow the storage of non-key field data in the NSF, in addition to the exter-nal system table. Typically, only the key fields are stored ‘natively’ in theNSF. Setting this option to “leave all (or selected) real-time fields indocuments” allows the specified, or all, external non-key fields to be poten-tially viewed when the activity is not running, or more typically to allownon-key data fields to be displayed in a Notes view. Virtual fields cannot bedisplayed in a Notes view unless they also stored in the document. Sincekey fields must always be stored in the document, they can thereforealways be displayed in a view.

Since here we are using virtual documents, not native key documents, thereis no longer any native storage of data in the NSF. However, the limitationon non-key virtual fields that prevents them from being displayed in Notesviews still exists. To allow them to appear in views, set the Data Storageoption to “leave all (or selected) real-time fields in documents”. In this caseof course, those “documents” are virtual documents, so there is anadditional requirement that any fields specified in this option must also bemapped in the Virtual Documents activity. This of course means there mustalso be corresponding columns in the Virtual Documents table. This maynot always be feasible or desirable. You can limit the fields to just theselected fields that will be displayed in views, and only those fields thenneed to be mapped in the Virtual Documents activity.

If there are any non-key fields that are otherwise mapped by both theVirtual Fields and Virtual Documents activity for other reasons, and theData Storage option is set to “remove all real-time fields from thedocument”, updates to those fields will be set to null in the VirtualDocuments table. If you wish to have updates to those fields occur in bothtables, you must enumerate them in the Virtual Fields activity Data Storageoption to “leave selected real-time fields in documents”, or simply set theoption to “leave all real-time fields in documents”. Also, if you don’t dothis, you may also receive errors from the external system if nulls are notallowed for any of the fields involved.

To summarize, since the virtual documents themselves are fully virtualizedNotes documents, all the fields mapped by the Virtual Documents activitycan always be displayed in any Notes view. However, any virtual fieldsmapped by the Virtual Fields activity cannot be displayed in the viewunless the Data Storage option is set to “leave all (or selected) real-timefields in documents”, and those fields must also be mapped by the VirtualDocuments activity.


Virtual Field Form Override OptionThis Virtual Fields activity option allows a Virtual Fields activity to monitorall forms in an NSF. Because Virtual Documents activities always monitoronly a single form, this option should generally not be enabled (it isdisabled by default) if you are trying to use a Virtual Fields activity tomonitor the same form as a Virtual Documents activity.

There may be special advanced circumstances where enabling this optionmay be desirable. Enabling this option may lead to a mix of virtual and‘native’ documents, all of which may contain virtual fields mapped by thesame Virtual Fields activity. For example, creating a document using a formmonitored by a Virtual Documents activity will create a virtual documentwith a corresponding insert into the Virtual Documents table, and a rowwill also be created in the Virtual Fields activity table. However, creating adocument using a form not being monitored by a Virtual Documents activ-ity will result in a native document being created, with the Virtual Fieldsactivity inserting a row into the Virtual Fields table for the virtual fieldsmapped by the activity.

Virtual Attachments OptionThe Virtual Attachments option is available in both Virtual Documents andVirtual Fields activities. It allows the storage of attachments into an externalsystem table instead of within the NSF. When using a Virtual Fields activityto monitor the same Notes form as a Virtual Documents activity, this optionmust only be enabled in Virtual Documents activity. By enabling VirtualAttachments in the Virtual Documents activity, all attachments in all theform’s rich text fields will be virtualized into the external system’s table.The rich text field(s) in which the attachments are placed can be mapped bythe Virtual Documents activity, or by the Virtual Fields activity(s). In otherwords, even though Virtual Attachments are enabled through the VirtualDocuments activity, the rich text field which contains the link(icon) to theattachment can be mapped by any of the activities monitoring the form.


Appendix E Using Virtual Activities in a Domino Cluster

This appendix describes how the Virtual Fields and Virtual Documentsactivities support the use of Domino clustering. It is assumed that you arefamiliar with these two activity types.

Virtual Activities and Domino ClustersVirtual Documents activities and Virtual Fields activities support Dominoclusters but to a varying degree. Virtual Fields, can fully support the failo-ver and load balancing capacity provided by a Domino cluster. AlthoughVirtual Documents will work in a Domino cluster, it currently does not fullytake advantage of these capacities. The following describes how to set upand use Virtual activities within a Domino cluster and the limitations.

A Domino cluster is a set of specified Domino servers that host one or morereplica databases (replicas) and for which Domino cluster replication isenabled. It's assumed that you are familiar with the configuration and useof Domino clusters. All the replicas in the cluster are kept in synchroniza-tion using an essentially event driven replication model. Modifications todata in any replica database in the cluster is almost instantly replicated tothe other replicas within the cluster. If any server, and therefore its replicadatabases, were to go off line for any length of time, traffic is automaticallyrouted to the other servers. When the server comes back online, it will beable to replicate with the other servers to bring its replica databases "up todate" with the current data. Load balancing among the servers in the clusteris achieved using a similar mechanism.

393

Virtual Fields Support for Domino ClustersFor Virtual Fields activities to fully participate in a Domino cluster, eachserver in the cluster must be set up with a Virtual Fields activity(s) whichmonitors the replica database(s) on that server. In other words, each serverin the cluster will have its own Virtual Fields activity(s) running against itslocal replica databases. Each server in the cluster must maintain it's owncopy of the LEI Administrator, with a copy of the activity(s) set up andrunning from each LEI Administrator database. The LEI Administratorcannot be cluster-replicated; each server must host it's own non replica copyof the LEI Administrator.

All the Virtual Fields activities can be set up to use the same external datasource. If set up in this fashion, cluster failover and load balancing supportderives from the fact that each Virtual Fields activity has access to, and canupdate, the external data. Even if all servers but one were to go off line, theexternal data would continue to be accessible and can be kept current. Asother servers come back online, the current external data would be instantlyavailable to those servers directly from the external data source.


Virtual Documents Support for Domino ClustersThe main difference between Virtual Documents support for Dominoclusters and Virtual Fields support for Domino clusters stems from thelimitation that a single external data table can map to only a single Dominodatabase/form. While it is possible to have a Virtual Documents activitymonitoring each replica database in the cluster, you cannot map each ofthose instances to the same external table, in the manner that wouldtypically be done with Virtual Fields. As a result, the typical configurationcalls for selecting a single Domino server in the cluster which will managethe virtual documents and the external data connectivity.

A Virtual Documents activity will monitor a replica database and form onthis one server, mapping its external data. This activity is responsible for allexternal data access and updates for the cluster. Other replicas in the clusterwill see this virtual data and it will be replicated throughout the cluster inthe normal manner, but will be held natively in the other replica databases.Only one replica in the cluster will be running a Virtual Documents activityand "contain" virtual documents. The other replicas will contain nativereplica documents. In this topography, the external data source becomesjust another node in the cluster, and can be detached from the cluster if theserver running the Virtual Documents activity becomes disconnected.However, like any other node, data changes made to cluster replicas will bepropagated to the server, and ultimately to the external data source, whenthe server comes back online.

Appendix E: Using Virtual Activities in a Domino Cluster 395

AAccessibility

tools, 11Activities

action bar, 43Activity Document fields, 59, 60,

62, 65, 67Admin Backup, 53, 85Admin Purge Log, 89Advanced RealTime, 69, 71, 74Archive, 93Command, 101command line execution, 75data mapping, 76dependent, 128description of supplied, 7Direct Transfer, 77–78, 109,

311, 321Direct Transfer, output

parameters, 118Direct Transfer, stored

procedures, 118Java, 280list of supplied, 57log, 51logging, 60Polling, 121, 321Replication, 77, 251, 321, 339scheduling, 62, 64–65, 67Scripted, 53, 283, 287, 291, 321Virtual Agents, 70, 237Virtual Documents, 70, 179Virtual Fields, 69, 131

Admin Backup Activity, 7Admin Purge Logs Activity, 7Administrator

configuration document, 48Advanced RealTime

activities description, 8Domino server cluster, 15specify Domino server, 50Virtual Fields introduction, 131with stored procedures, 311

Agentopen, 339

Archive Activity, 7

BBrowsing

buffering, 46connections from activity

document, 58Domino directory, 45error messages, 58fields, 58in Advanced RealTime

activities, 312names.nsf, 44server-side, 45with Virtual Agents, 240

CCluster, 28

Domino and AdvancedRealTime, 15

with iSeries, 16Command Activity, 7Connections

connectivity, 45, 58Connectors

array transfer, 14File, 107list of supplied, 6, 55Lotus Connector for DB2,

118, 310Lotus Connector for Files, 119Lotus Connector for OLE DB, 141Lotus Connector for SAP, 118support for output parameters,

175, 177contents

using required VirtualAttachment field, 364

Customer support, xii

DData mapping, 73, 76, 97, 119,

180, 200columns in Virtual Fields, 135in activities, 76Virtual Fields, 141

Data transferacross platform, 81

Data typesindexing, 135LEI, 293NULL, 295with Virtual Documents, 187

DB2 Connectoridentity column support, 76stored procedures and output

parameters, 78DB2/400, 311dbib


decsadm.nsf, 27, 28Deletion stubs, 193DestTimeStamp, 254Direct Transfer Activity, 7, 311,

321, 327tutorial, 323

Documentationlist, 36, 322Lotus Developer Domain

(LDD), 9PDF files, 9www.notes.net, 27, 29, 36

DominoLEI addin task, 21

Domino clusterintegrated credentials, 217with Virtual Documents, 393with Virtual Fields, 393

Domino Designer, 339Domino directory, 44, 313

browsing, 45Domino server

LEI Advanced RealTime, 50

397

Index

EEIMODIFIED, 189, 210EINOTEID, 210EINOTEPROPS, 182, 186, 188, 192,

210, 212EIUNID, 191, 210

Notes document uniqueidentifier, 180

Encryption, 29, 134, 182public key fields, 192

External data systemsaving data to Virtual Fields, 366

External key table, 191–192considerations, 213required column data types, 210with Virtual Documents, 186with Virtual Documents

activity, 209writeback, 214

Ffileid


filenameusing required Virtual

Attachment field, 364filesize


Filter formulasin Virtual Fields, 366

fixupand Virtual Attachments, 164, 218

HHTTP, 310HTTP client

Virtual Agents, 249HTTP server

with Virtual Fields, 135

IIndexing

field list, 192in Virtual Attachments to

increase performance, 165, 219in Virtual Documents, 187, 191key fields, 135

performance, 14performance in Advanced

RealTime activities, 15rebuild using Shift + F9, 189Virtual Documents, 214Virtual Fields, 134

Initialize keysin Virtual Fields, 157

Integrated credentialwith Virtual Agents, 249

Integrated credentials, 71, 74full text indexing, 216in a Domino cluster, 217in Virtual Agents, 248in Virtual Documents, 215in Virtual Fields, 161, 169server to server replication, 216with Virtual Documents, 161

iSeriesconsole commands, 23, 24job logs, 310language support, 17LEI server, 23qnotes, 17terminology, 17tips for use with LEI, 16, 310troubleshooting, 308

JJava Activity, 7java.exe, 281JVM, 281

KKey documents, 133–134, 182,

379, 381Virtual Fields, 132

Key fieldsindexing, 135

Key initialization, 386

Llccon6.nsf, xi, 29, 55

Lotus Connectors andConnectivity Guide, 36

LCConnection class, 284LCSession class, 284LEI Activities Log

activity, 51LEI Activity Log, 8

LEI AdministratorActivity views, 33author privileges, 29, 44configuration document, 47configuration view, 34Connections view, 34introduction, 5, 27user assistant, 9, 35user documentation, 9

LEI Script Vault, 53, 283, 338LEI server, 28, 39

command to invoke, 19commands, 20console commands, 20iSeries, 23log, 8partitioned, 19

leiact.exe, 75leiadm.ntf, 28leicgi.exe, 75leiclean script, 22leicred.ntf, 71, 74, 161, 216, 249leidoc.nsf, xi

Lotus Enterprise IntegratorActivities and User Guide, 36

leiempsamp.nsf, 13, 322–323, 330,332–333, 346, 348–349

leiig.nsf, xi, 27Lotus Enterprise Integrator

Installation Guide, 36leilog.nsf, 8, 28, 51leipackagetrack.nsf, 53, 283, 321–322,

339, 351–352, 358leivlt6.nsf, 53, 283, 288, 339

supplied agents, 321–322lsxlc6.nsf, xii, 29

Lotus Connectors LotusScriptExtensions Guide, 36

MMemdata, 182Metaconnectors

list of supplied, 6Multi-value data

in Virtual Fields, 158

Nnlei.exe, 19nleiact.exe, 75noteid



Notes Agent, 288notes.ini, 107

EICenturyBoundary, 295ServerTask, 21

NT serviceLEI, 22

NULL, 134, 141, 182, 193, 200in Virtual Fields and Virtual

Documents, 135

OOrder Metaconnector

replication sort order, 256Output parameters, 109, 118

in Virtual Fields, 171

PPasswords

encryption, 28PDF files, 58Performance

array transfer, 14database index, 14Direct Transfer, 13in Direct Transfer activity, 117indexing in Virtual Documents,

191, 214indexing Virtual Documents,

187, 219indexing Virtual Fields, 135, 165Replication, 13

Pollingconsiderations, 128interval, 121scheduled, 128timestamp, 123trigger-based, 123

Polling Activity, 8, 321tutorial, 327

Rreadme.txt, xiiRealTime

see Virtual Fields, 69Replication

conflict handling, 265key fields, 262logging, 265primary key, 251, 265, 311restrictions, 274skip deletions, 273–274, 278

skip insertions, 273–274, 276skip updates, 273–274, 277sort order and key fields, 256–257timestamp, 251, 253–254, 256,

263, 271, 311timestamp results, 270, 274

Replication Activity, 8, 321tutorial, 332

Replication idand Virtual Agents, 240

SSample database

leipackagetrack.nsf, 283Sample databases, 322, 323Scheduling

example, 129restrict to schedule, 128start and stop times, 128

Scripted Activity, 8, 321tutorial, 338, 346

SecurityACL, 28in Advanced RealTime activities,

312integrated credentials database,

71, 74LEI Administrator, 28password encryption, 29Virtual Documents, 182, 191Virtual Fields, 134

SrcTimeStamp, 254Stored procedures, 109, 118, 311

examples used in Virtual Fields, 371

in Advanced RealTime activities, 313

in Virtual Fields for Sybase andSQL, 369

mapping, 73testing DB2 in Virtual Fields, 373testing SQL in Virtual Fields, 371using Oracle and Virtual

Fields, 375with Virtual Agents, 238with Virtual Documents, 229

Stored procedures and outputparameters

in DB2, 78Stub documents, 133–134, 182

Virtual Fields, 132Subkeys

use caution when updating, 161

TTable creation utility

Create virtual attachment table inVirtual Documents, 220

Create virtual attachment table inVirtual Fields, 167

Terminologyagent, 338common LEI terms, 10conflict, 265correlating Notes and relational

database, 293iSeries, 17LEI Administrator, 5LEI server, 5

Timestamp polling, 123Trigger-based polling, 123Troubleshooting

on iSeries, 308–309using activity logs, 307

Tutorialsintroduction, 321

UUNID

as key field, 141, 150

VVirtual Agents, 70

example, 238, 244HTTP client, 249integrated credentials, 248introduction, 237options description, 246stored procedures, 238used with Virtual Fields, 178using a URL, 249

Virtual attachment tablewith Virtual Documents

activity, 220with Virtual Fields activity,

166–167Virtual attachments

columns, 163in Virtual Documents, 164, 218in Virtual Fields, 163indexing fields to increase

performance, 165, 219Virtual Attachments Activity

example, 364Virtual Documents, 70

Index 399

connection security, 191control data column names, 186create external key table, 220data types, 187Deletion stubs, 193in Domino cluster, 393integrated credentials, 215monitored forms, 183replication ID, 196stored procedures, 229with external key table, 186,

209, 210with Virtual Fields, 132, 180,

377–378, 380, 387Virtual Documents Activity, 8

example, 363Notes Application using Virtual

Attachments, 359Virtual Fields, 69

create external key table, 167example, 136, 147in Domino cluster, 393indexing, 134initialize keys, 157integrated credentials, 161key documents, 132mapping key and data fields, 149monitor order, 132multi-value data, 158option description, 169stub documents, 132used with Virtual Agents, 178with Virtual Documents, 132, 180,

377–378, 380, 387Virtual Fields Activity, 8

accessing different externalsources, 366

building views, 367data storage options, 367example, 362example query Notes or Web

clients, 351filter formula, 366monitor orders, 367Notes Application using Virtual

Attachments, 359saving data to external

system, 366static copy of external data, 367testing stored procedures in

SQL, 371

using an Oracle stored procedure, 375

using stored procedures inSybase/SQL, 369

Virtualizingexisting data, 184

WWeb sites

accessibility, 11DECS, xiiLEI, xiiLEI documentation, xiiPTFs, xii

Writeback, 214www.notes.net, 9, xii, 55


· Step 9: Select Scheduling Options..... 202 Step 8: Select Options..... 202 Step 7: Name the...

Documents

Transcript of · Step 9: Select Scheduling Options..... 202 Step 8: Select Options..... 202 Step 7: Name the...