DECS Installation and User Guide

COPYRIGHT Under the copyright laws, neither the documentation nor the software may be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form, in whole or in part, without the prior written consent of IBM Corporation, except in the manner described in the documentation or the applicable licensing agreement governing the use of the software. ©Copyright 1985 - 2002 Lotus Development Corporation ©Copyright 2002

IBM Corporation Lotus Software, IBM Software Group One Rogers Street Cambridge, MA 02142

All Rights Reserved.

List of Trademarks Domino, cc:Mail, Notes, NotesBench, Domino Connectors, Domino Enterprise Connection Services, IBM Lotus Enterprise Integrator for Domino (LEI), and Notes/FX are trademarks; and Freelance, Freelance Graphics, Lotus, Lotus Notes, LotusScript, Notes Mail, NotesSQL, NotesView, 1-2-3, Organizer, SmartIcons, and SmartSuite are registered trademarks of Lotus Development Corporation and/or IBM Corporation in the United States, other countries, or both. OS/2 Warp and PowerPC are trademarks and IBM, AIX, DB2, OS390, iSeries, zSeries, and pSeries, OS/2 Presentation Manager, and SNA are registered trademarks, and DB2/2, DB2/400, and RS/6000 are trademarks of International Business Machines Corporation. Tivoli/Courier is a trademark of Tivoli Systems and/or IBM Corporation in the United States, other countries, or both. All other trademarks are the property of their respective owners.

Disclaimer THIS DOCUMENTATION IS PROVIDED FOR REFERENCE PURPOSES ONLY. WHILE EFFORTS WERE MADE TO VERIFY THE COMPLETENESS AND ACCURACY OF THE INFORMATION CONTAINED IN THIS DOCUMENTATION, THIS DOCUMENTATION IS PROVIDED “AS IS” WITHOUT ANY WARRANTY WHATSOEVER AND TO THE MAXIMUM EXTENT PERMITTED, LOTUS DISCLAIMS ALL IMPLIED WARRANTIES, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF MERCHANTABILITY, NONINFRINGEMENT AND FITNESS FOR A PARTICULAR PURPOSE, WITH RESPECT TO THE SAME. LOTUS SHALL NOT BE RESPONSIBLE FOR ANY DAMAGES, INCLUDING WITHOUT LIMITATION, DIRECT, INDIRECT, CONSEQUENTIAL OR INCIDENTAL DAMAGES, ARISING OUT OF THE USE OF, OR OTHERWISE RELATED TO, THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION. NOTWITHSTANDING ANYTHING TO THE CONTRARY, NOTHING CONTAINED IN THIS DOCUMENTATION OR ANY OTHER DOCUMENTATION IS INTENDED TO, NOR SHALL HAVE THE EFFECT OF, CREATING ANY WARRANTIES OR REPRESENTATIONS FROM LOTUS (OR ITS SUPPLIERS OR LICENSORS), OR ALTERING THE TERMS AND CONDITIONS OF THE APPLICABLE LICENSE AGREEMENT GOVERNING THE USE OF THIS SOFTWARE.

Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . v

............... v Contact and Support Information . . . . . . . . vi 1 Introduction . . . . . . . . . . . . . . . . . . 1 Organization of this Manual . . . . . . . . . . . . 1 Introduction to DECS . . . . . . . . . . . . . . . . 2 Virtual Fields Activity . . . . . . . . . . . . . . 2 Supported Data Sources .............. 3 Accessibility . . . . . . . . . . . . . . . . . . . . . . 3 Security . . . . . . . . . . . . . . . . . . . . . . . . . 4 2 Installing DECS . . . . . . . . . . . . . . . 5 DECS Installation . . . . . . . . . . . . . . . . . . . 5 Related Documentation

After Upgrading to DECS Replace Administrator Design . . . . .

.......

DECS Virtual Fields Activities in a Clustered Domino Server Environment

6

. 6 Installation Considerations . . . . . . . . . . . 6 DECS and Access Control List (ACL) Levels . . 6 Running Restricted LotusScript Agents . . . 7 Uninstalling DECS . . . . . . . . . . . . . . . . . . 7 3 DECS Administrator . . . . . . . . . . . 9 The DECS Administrator . . . . . . . . . . . . . . 9 DECS Administrator Navigator ......... 9 Connections View . . . . . . . . . . . . . . . . . 12 Activities View . . . . . . . . . . . . . . . . . . . . 12 Favorites View . . . . . . . . . . . . . . . . . . . . 15 Main Menu Commands . . . . . . . . . . . . . . 17

... Defining Lotus Connections . . . . . . . . . . . Connection Document Fields . . . . . . . . . . . Using the Manual Button . . . . . . . . . . . . . Completed Connection Document . . . . . . . 5 Virtual Fields Activities . . . . . . . Introduction to Virtual Fields Activities . . . . 4 Defining Lotus Connections

Usage Requirements for Virtual Fields Activities . . . . . . . . . . . . . .

.....

Using the Activity and Connection User Assistant . . . . . . . . . . . . . . . . Turning the User Assistant On Turning the User Assistant Off

.... ........ .......

Establishing Access Control in the Domino Directory . . . . . . . . . . . . . . . . .

19 21 23 24 25 25 28 29 29 30

..

30

... ... ...

31

.....

33

Creating a Virtual Fields Activity with the User Assistant . . . . . . . . . . . . . Step 1 — Click the Add Activity Icon Step 2 — Select the Domino Database Step 3 — Select the Domino Form to Monitor . . . . . . . . . . . . . . .

19

31 32

Step 4 — Select the Lotus Connection for the Data Source . . . . . . . . . . . . .

34

Step 5 — Map Data Field(s)

36

.. ..........

Step 6 — Virtual Fields Activity Events to Monitor Selection . . . . . . . . . . . . .

. Step 7 — Name the Activity Document . . Step 8 — Enable Subforms . . . . . . . . . . Step 9 — Select Options . . . . . . . . . . . . Step 10 — Select Scheduling Options . . . .

37 38 39 39 39

iii

. ...........

Step 11 — Save and Close the Document

39

Step 12 — Initialize Keys

40

Step 13 — Process the Virtual Fields Activity . . . . . . . . . . . . . . .

.....

40

..... Step 1 — Click the Add Activity Icon . . . Step 2 — Enter a Name for the Activity . .

40

Creating an Activity without the User Assistant . . . . . . . . . . . . . .

Step 3 — Select the Domino Application and the Form to Monitor . . . . . . .

Step 8 — Select Options and Initialize Keys

43

42 43 43

43 43 43 44 44 45 49 50 52 53 55 57 59 61 62 63

............... ..

Saving Data to an External Data System

69 70

Accessing Different External Sources using the Same Notes Application . . . . . . . 70

........... Building Views . . . . . . . . . . . . . . . . . Storing a Static Copy of External Data . . . Using the Monitor Orders Option . . . . . . . . Using Stored Procedures in Sybase/SQL . . . Sybase/SQL Stored Procedure Example . .

73

Testing the Stored Procedures in Sybase/SQL

75

.......... Using an Oracle Stored Procedure . . . . . . . Input Values and Named Parameters . . . Output Parameters . . . . . . . . . . . . . . .

77

Using Data Storage Options

Using a DB2 Stored Procedure

71 71 71 71 73

79 79 80

8 Virtual Fields and Dynamic Queries . . . . . . . . . . . . . . . . . . . . . . 83 Overview of Virtual Fields Dynamic Queries

83

Virtual Fields Dynamic Queries from Web Clients . . . . . . . . . . . . . . . . . . .

84

Overview of Steps

.. ................

Example of Virtual Fields Dynamic Queries from Notes Clients . . . . . . . . . . .

..

84 86

Appendix A Configuration and Troubleshooting . . . . . . . . . . . . . . . 89 Index . . . . . . . . . . . . . . . . . . . . . . . . . 103

Building a Domino Application for a Virtual Fields Activity . . . . . . . . . . . . . . .

63

Example Application

64

iv DECS Installation and User Guide

7 Using Virtual Fields Activity Options . . . . . . . . . . . . . . . . . . . . . . 69

Using Filter Formulas

42

. ...............

67

41

.. Step 5 — Enable Subforms . . . . . . . . . . Step 6 — Mapping . . . . . . . . . . . . . . . Step 7 — Select Event(s) to Monitor . . . . .... Step 10 — Save and Close the Document . Step 11 — Initialize Keys . . . . . . . . . . . Step 12 — Process the Activity . . . . . . . . Options Overview . . . . . . . . . . . . . . . . . General Options .................. Initialize Keys . . . . . . . . . . . . . . . . . . . . Multivalue Data in Virtual Fields . . . . . . . . Event Options . . . . . . . . . . . . . . . . . . . . Document Create Options . . . . . . . . . . Document Open Options . . . . . . . . . . . Document Update Options . . . . . . . . . . Document Delete Options . . . . . . . . . . . Scheduling . . . . . . . . . . . . . . . . . . . . . . Virtual Fields Activity Logging . . . . . . . . . 6 Building a Domino Application .

66

Using the Options in a Virtual Fields Activity Document . . . . . . . . . . . . . . . . . . . 69

41

Step 9 — Select Scheduling Options

65

40

..

Step 4 — Select the Lotus Connection for the Data Source . . . . . . . . . . . . .

... Virtual Fields Activity Example . . . . . . . . . Running the Virtual Fields Activity . . . . . . Example of the Application Design View

Preface This document provides information about installing and using the Domino Enterprise Connection Services™ (DECS) application. Information about Lotus® Connectors and connectivity is described in the companion 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 Documentation This section lists documentation that you may find useful as you learn about and use LEI. LEI Documentation Set Documentation for DECS is available online with the product distribution and at http://www.notes.net. The DECS documentation set is listed below: •

Domino Enterprise Connection Services (DECS) Installation and User Guide — Provides information about configuring DECS and information on how to set up and use DECS activities.

•

Lotus Connectors and Connectivity Guide — Provides information on how to set up and use the supplied Lotus Connectors, including information about required software and instructions for testing connectivity (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.

•

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

Current information about DECS can also be found at http://www.lotus.com/ei. Other Documentation For more information about related tools, refer to the following documents: •

Domino Administrator’s Guide — This manual provides information for configuring and administering a Notes installation. v

•

LotusScript Language Reference — This manual provides information about writing LotusScript programs. This could be useful if you want to use the Domino LotusScript Extensions (LSX) to write custom Activities.

•

Additional Lotus Connector Documentation — Lotus Software, IBM Software Group sells additional Lotus Connectors for enterprise systems including Enterprise Resource Planning (ERP) and Transaction Processing Systems. Specific documentation about those Connectors is included with the specific Connector software and package. You may need documentation for the specific databases, ERP, or transaction processing systems that you are using.

Contact and Support Information Lotus Software, IBM Software Group provides extensive support for its products. Enterprise Integrator Web Site To obtain the latest information about DECS, visit the following Web site: http://www.lotus.com/ei

Note Domino-related product updates for iSeries can be found at following Web site: http://www-1.ibm.com/servers/eserver/iseries/domino/support/qm u.htm

Technical Support To contact Customer Support with suggestions or questions regarding your Lotus Connector or DECS application, call 1-800-346-6388.

vi DECS Installation and User Guide

Chapter 1 Introduction Domino Enterprise Connection Services (DECS) is an optional feature of Domino 6. This chapter provides information about the organization of this manual and includes an overview of DECS Virtual Fields activities (previously known as DECS RealTime activities).

Organization of this Manual This manual contains the sections described below. Section

Description

Chapter 1 Introduction

This chapter provides information about the organization of this manual. It also includes an introduction to DECS Virtual Fields activities, lists supported data sources, accessibility information, and contact and support information.

Chapter 2 Installing DECS

This chapter provides information about installing and configuring DECS.

Chapter 3 DECS Administrator

This chapter provides information about the DECS navigator, views, icons, and menu commands.

Chapter 4 Defining Lotus Connections

This chapter provides information and instructions for creating Connection Documents.

Chapter 5 Virtual Fields Activities

This chapter provides an overview of Virtual Fields activities, information regarding preparation of external system fields, and instructions for creating Virtual Fields Activities.

Chapter 6 Building a Domino Application

This chapter provides information for creating a Domino application for use with a Virtual Fields Activity.

Chapter 7 Using Virtual Fields Activity Options

This chapter provides examples using Virtual Fields options to refine the results of Virtual Fields Activities. continued

1

Section

Description

Chapter 8 Virtual Fields and Dynamic Queries

This chapter provides information on how to use Virtual Fields for on-demand, dynamic queries of external data.

Appendix A Configuration and Troubleshooting

This appendix provides information about notes.ini variables, using DECS with clustered Domino servers, error messages and known problems that you may encounter under certain conditions while using DECS.

Introduction to DECS This release of DECS replaces RealTime activities with Virtual Fields Activities. The functionality of Virtual Fields activities consists of all the functionality available in the earlier DECS RealTime activity as well as features not available in the earlier RealTime activity: •

Support for computed subforms

•

Options for new line delimiters

•

Additional logging options

•

Support for procedure return parameters following insert and update operations. Output from write operations allows results to be returned to fields in the Notes document being monitored following insert and update operations.

Virtual Fields Activity Virtual Fields Activities (previously known as DECS RealTime Activities) enhance Lotus Notes applications by allowing them to retrieve external data, such as data from DB2, and to integrate this external data with native Notes data on a single Notes document form. DECS, running on the Domino Server that is hosting the Notes application, intercepts and handles the Notes database events. For example, when Notes or Web client users open, create, update, or save Notes documents, these events trigger immediate access from the Notes form to external data sources supported by DECS. Once a system administrator has created a Virtual Fields activity, Domino users can open, create, update or delete external system data directly and transparently through their Notes Client. By extension, Web clients may open the same Notes form that the activity monitors by accessing a Domino Release 5.0.5 or Domino 6 server, obtaining access to supported external source data. 2 DECS Installation and User Guide

For example, if the external database is a DB2 database, Notes end-users may work with DB2 data as if it were in Notes. DB2 connectivity software is not required on each user’s system; however, it must be installed on the Domino server machine. Access to the external data source is handled by the Domino server machine, which uses DECS connectivity software to access the external data source, such as DB2.

Supported Data Sources Virtual Fields activities support a range of external data sources, called Connectors. Additional data sources are continuously being added. As Lotus and other third parties create data source Connectors for Domino, they will all be manageable using the Domino Enterprise Connection Services (DECS) product. Currently supported data sources include: •

DB2

•

OLEDB

•

Open Database Connectivity (ODBC)

•

Oracle 7

•

Oracle 8

•

Sybase

•

File

Each of the data sources has specific software requirements for network connectivity that must be met by the Domino Server. Refer to the Lotus Connectors and Connectivity Guide for information about the connectivity requirements for each of the supported data sources. Verify that all of your database software is up to date with all available maintenance releases and fix packs. Note Other Enterprise Resource Planning connectors and Transaction System Connectors are also available. For more information, see the Enterprise Integrator Web site: www.lotus.com/welcome/ei.

Accessibility Accessibility features help a user who has a physical disability, such as restricted mobility or limited vision, to use software products successfully. DECS adheres to the IBM and Lotus Notes R5 Accessibility guidelines. For more information on Accessibility, see http://www-3.ibm.com/able/guidelines.htm Chapter 1: Introduction 3

DECS provides keyboard access as an alternative or to augment its graphical user interface. You can tab from one field on a DECS Connection Document or Activity Document to another. You can also use the up and down arrow keys to move the cursor and change focus. You can use the Return key, for example, to select an action such as an Activity choice from the DECS Administrator. You can then use the arrow keys to move the cursor to the desired activity name. You can then press the Return key to select that activity and open the corresponding Activity Document. Once an Activity Document is open, you can enter Edit mode by pressing E. When you are in Edit mode, field level help displays automatically for whatever field has focus. Field level help appears at the bottom of the user interface. Note Pop-up help is available for all Connection Document and Activity Document options using the mouse, but it is not available with the keyboard. To simplify user interaction with the application, DECS supports the shortcut keys 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 display help on any of its content, press and the underlined character (for example, F for File, E for Edit). Keyboard equivalents are listed to the right of all pull-down menu choices. You can use screen-reader software and a digital speech synthesizer to hear what is displayed on the screen. You can also use voice recognition software, such as IBM ViaVoice, to enter data and to navigate the user interface.

Security See Appendix A and review the Domino release notes for information regarding security and access control.

4 DECS Installation and User Guide

Chapter 2 Installing DECS This chapter provides information about installing DECS on Domino 6 and describes current functional limitations.

DECS Installation Domino Enterprise Connection Services (DECS) is a forms-based technology in Domino that provides the capability to integrate live data from enterprise systems natively into Domino applications. DECS is installed as part of all new Domino 6 installations and upgrades but you must select the DECS option to activate its functionality when you install Domino 6. DECS installation is a simple process, simply elect to install DECS when you install Domino. But please see the following section, “DECS and Access Control List (ACL) Levels,” for additional suggestions and Name and Address Book setting. Note Make sure that all users who will be creating DECS activities have entries in the Name and Address book and that the server is listed as part of a group. For more information, see the pop-up help in the Domino Directory (formerly referred to as the Server Name and Address book). Note If after upgrading to DECS, you are unable to get data when running Virtual Fields activities, open each Virtual Fields activity document and ensure that the specified Domino Server is correct. As part of the install process in Domino 6 and Notes 6, the following DECS documentation databases are installed: For Domino server installations, the following three document databases are installed: •

Domino Enterprise Connection Services (DECS) Installation and User Guide (decsdoc6.nsf)

•

Lotus Connectors and Connectivity Guide (lccon6.nsf)

•

Lotus Connector LotusScript Extensions Guide (lsxlc6.nsf)

5

For Notes client installations, the following two document databases are installed: •

Lotus Connectors and Connectivity Guide (lccon6.nsf)

•

Lotus Connector LotusScript Extensions Guide (lsxlc6.nsf)

After Upgrading to DECS Replace Administrator Design After a Domino 6 upgrade, you must manually replace the design on the DECS administrator prior to running any activities. When you replace a DECS administrator design, Domino has to be running. Any scheduled DECS activities will launch once Domino is started, these activities should be stopped prior to replacing the design. Once the design replace is complete, the activities can be restarted. Another approach is to disable DECS the first time you restart Domino 6 after an upgrade, replace the design, re-enable DECS and restart the server. Use the supplied decsadm.ntf database to replace the design. Design replacement follows standard Domino procedures, see Domino documentation for more information.

DECS Virtual Fields Activities in a Clustered Domino Server Environment If you plan to use DECS in a clustered Domino server environment, see “Using DECS Virtual Fields Activities in a Clustered Domino Server Environment” in Appendix A.

Installation Considerations The following should be considered before installing DECS: •

The DECS Virtual Fields activity does not work in true real-time with Domino clustering. Writing changes to the external system database may be delayed if not all databases within the cluster are DECS-enabled.

DECS and Access Control List (ACL) Levels The DECS administrator is shipped with a predefined Access Control List (ACL). In this ACL, “Default” is set to Manager because when DECS is first installed and the addin task is loaded for the first time, DECS automatically builds the initial administrator from the template — there is no opportunity for a user to set themselves as the database administrator.


Managers and administrators are urged to change the ACL to best fit their environment as soon as possible after installation so that only the appropriate people have the access they require. Note Either a “Default” or “Lotus Notes Template Development/Lotus Notes” ACL entry must exist and must have at least Editor access or browsing will fail. This is because the agent that is used for browsing is run on the server, therefore security is through the signer of the agent, which is “Lotus Notes Template Development/Lotus Notes.” System administrators can further secure the system by specifying the Template development ID (that is, Lotus Notes Template Development /Lotus Notes) in the Server entry in the Name and Address book in the “Run Restricted LotusScript/Java agents” list. This will only allow that ID to run LotusScript agents on that server (this is very restrictive and may be too excessive for most installations). For additional information, see the following section, “Running Restricted LotusScript Agents.”

Running Restricted LotusScript Agents To execute unrestricted LotusScript agents you must grant permission to “*”. In addition, either “Default” or (more secure) the signer of the agent must have Editor access to the DECS Administrator database with permission to delete documents.

Uninstalling DECS When you elect to install DECS during a Domino installation, two entries are added to the NOTES.INI file. If you need to disable DECS for any reason, delete the following items (highlighted in italics) from the notes.ini file and restart the server. ServerTasks=....., DECS EXTRMGR_ADDINS=decsext

To re-enable DECS, simply add the two entries back into the notes.ini file and restart the server. Adding an Empty DECS Administrator If you want to start with an empty (fresh) DECS administrator, rename or delete the existing Administrator (decsadm.nsf) in the server data directory. Restart the server with DECS enabled. A new administrator is automatically created during the server startup. Note Do not move or delete the DECS ntf file (decsadm.ntf) at any time.

Chapter 2: Installing DECS 7

Chapter 3 DECS Administrator This chapter provides information about the DECS Administrator, including its navigator, views, and menu commands.

The DECS Administrator The DECS Administrator provides an interface that makes it possible for you to view connections and activity documents, create activities and connections, and manage all of these components. There are three distinct views available to you in the Administrator. •

Activities — This view displays all of the existing Activities and their state (running, disabled, what type of activity they are, and so on).

•

Connections — This view displays all of the existing connections. It also shows which external database the connector is accessing and which table, view, or procedure is being used.

•

Favorites — This is a folder that contains whatever activity and connection documents you choose to drag into it. You can create more views of this type as you want. The Action bar options for these remain the same.

An example of each view is illustrated below as well as the navigator, action bar, views, and menu commands in the Administrator. All are described in the sections that follow.

DECS Administrator Navigator The Navigator panel on the left side of the Administrator is present in all views. It contains these icons: •

Activity — Click this icon to see the Activities view.

•

Connections — Click this icon to see the Connections view.

•

Favorites — Click this icon to see the Favorites view.

•

Info — Click this icon to open a document with an illustration and a description of all of the icons used in the Administrator. 9

•

Help — Click this icon to open the DECS Administrator help documentation.

•

Running — Click this icon to open a dialog box showing the currently running activities. Click again to close the dialog box.

•

Assistant — Click this icon to turn the User Assistant on or off. When the User Assistant is turned on the New Activity/Connectivity Wizard is enabled. The Wizard guides you through creating a Virtual Fields activity document and provides information about creating and editing an activity document.


The following illustration shows the Navigator with the Running Activities window open. To see the activity listed by Notes application, click “By Notes App”; to see the activities listed by external system application, click “By External Sys.”

Chapter 3: DECS Administrator 11

Connections View Lotus Connection documents are named automatically by the DECS task using a convention that specifies the external system, the database, and the table name; when applicable, the user name required for login to the data source is shown in parentheses. For example, DB2, DB2V5_2, (using ‘mylogin’) — QEPUMP.KLBVD_EXT. The Connections view Action bar contains an icon that enables you to create a connection: •

Add Connection — Click this icon to create a new connection document for an external data source. When the User Assistant is active, this launches the Wizard, which steps you through the process of defining a Connection to an external data source.

Below is an illustration of the Connections view.

Activities View In the Activities view, you can see all of the Virtual Fields activities that have been created in the Administrator. In the Activities view Action bar, the following icons enable you to create and work with Activities:


•

Add Activity — Creates a new activity. When the User Assistant is active, this launches a wizard that prompts you through the process of defining a Virtual Fields activity. When the User Assistant is turned off, this displays a blank activity document that you can edit directly.

•

Start — Start the currently selected activity. This has no effect if the current selection is already executing.

•

Log — See the log for the highlighted activity. Displays the status of the currently selected activity. If the current selection is running, the start time and other current status are displayed. If the current selection is not running, this will display the results of the most recent execution.

•

Stop — End execution of the currently selected activity. This has no effect if the current selection is not running.

Activity View Below is an illustration of an Activities view.


Activity Icons The following table describes the information shown in the Activities view of the DECS Administrator. Column

Description and Icon

Domino Application

Shows the name of the Notes NSF and the specific form being monitored.

Events

Indicates the activity will process document creations. Indicates the activity will process document opens. Indicates the activity will process document updates (edit/save). Indicates the activity will process document deletions.

Activity

Indicates the activity is a Virtual Fields activity.

External Source

Shows the type of external data source, the database and table name or metadata.

Status

Shows the status of the activity, as indicated by the icons below. Refresh the view periodically to update the status. New activity. Active activity. Starting / Stopping an activity. Activity stopped with an error. Activity disabled with an error. Activity scheduled to AutoStart with server. Activity not scheduled. Activity scheduled to start and stop at specified times.

Name


The user-specified name of the Activity.

Favorites View The Favorites view is a view that you can use to show both connections and activities (by dragging and dropping them into the Favorites folder on the Navigator). In the Favorites view Action bar, the following icons enable you to create both Connections and Activities and to work with Activities: •

Add Activity — When the User Assistant is active, this launches a wizard that prompts you through the process of defining a Virtual Fields activity. When the User Assistant is turned off, this displays a blank activity document that you can edit directly.

•

Add Connection — Click this icon to create a new connection document for an external data source. When the User Assistant is active, this opens a connection document with a detailed description of the steps you go through in the process of defining a connection to an external data source.

•

Start — Start the currently selected activity. This has no effect if the current selection is already executing.

•

Log — Displays the status of the currently selected activity. If the current selection is running, the start time and other current status are displayed. If the current selection is not running, displays the results of the most recent execution.

•

Stop — End execution of the currently selected activity. This has no effect if the current selection is not running.

•

Remove from Folder — Select the activity or connection document that you want to remove from the folder then click “Remove from Folder.”


The following is an illustration of an empty Favorites view, no activities or connections have been brought into it.

You can add additional views that are identical in function to the Favorites view. You can name these Views whatever you want to. Use a name that reflects the kind of information you are monitoring — for example, “South American Sales.” Then move activities and connections that are unique to this folder or shared by other folders into this folder. See the following illustration.


Main Menu Commands In addition to the Notes commands found in the menus, the DECS Administrator menus provide specific commands for working with DECS. Create The following commands are available from the main menu under Create: Command

Description

Other...

Opens a dialog box from which you can select the type of connection document that you want to create. Provides the same functionality as clicking “Add Connection” in the Action bar.

Actions The following commands are available from the main menu under Actions: Command

Description

Reset Activity

Restarts the currently selected activity.

Set Autostart

When this option is turned on all the selected activities start when Domino starts. Clicking “Off” turns off this option for the selected activities.

Remove from Folder

Remove the selected activity and connection documents from the currently opened folder. This menu option is only available when the Favorites folder is open, or when a folder view you have created is open. Provides the same functionality as clicking “Remove from Folder” in the Action bar.


Chapter 4 Defining Lotus Connections This chapter provides information and instructions for creating Lotus Connection documents.

Defining Lotus Connections You use the Lotus Connection document to define connections to external data sources. You can use the Wizard or you can fill out the fields in the document without using the Wizard. If you use the Wizard, the connection document opens with explanatory text at the top of the document (see the illustration in step 3), if you do not use the Wizard, the connection document opens without explanatory text. In either case, refer to the steps below. Note In order to connect to a supported data source, you must have the required connectivity software for that data source installed on your server. Verify that all of your database software is up to date with all available maintanence releases and fix packs. 1. Click the Add Connection icon.

2. A list of supported data sources appears, as shown below.

19

Note You can remove any of the supported data sources that you do not intend to use from the list. Refer to the Notes Application Developer’s Guide for more information on how to remove a form from a menu. 3. Select the data source for which you want to define a connection from the list of available sources and click OK. The Lotus Connection document appears. Below is an example of a Lotus Connection for a Sybase document. Note Note that the text in the top part of the document only appears when the Wizard is turned on.

4. Enter the required information in the Lotus Connection document. The Connection document is divided in two sections: • Connectivity — This section of the document specifies the database or data source and the connectivity information required to access that data source.


• Table/View/Procedure/Subdirectory Selection — Use this section of the document to select the specific metadata that you want to access through this Connection. The title of this section varies depending on the type of data you want to access.

Connection Document Fields The tables below describe the fields in each section of the Lotus Connection document. The number and title of these fields may change depending on the external system and the type of connection you select. Note For information about Connection documents for the various external systems that DECS supports, see the Lotus Connectors and Connectivity Guide (lccon6.nsf). Connectivity Field

Description

Server/Provider/Oracle Version/SQL Server Note This field is not available for all Connection documents.

Select Oracle version, enter the name of the Sybase SQL Server where the database is located, or relational database engine to use, or programmatic ID for OLE DB provider to use.

Database/Engine/Directory Path/Data Source/Host String Provider String Authentication Service

Enter the information required for the specific data source for which you are defining a connection. This information can vary according to the type of data source selected. Note Depending on the connector, more than one field may be exposed to capture all of the required database information.

User Name

Enter the User Name required to access the selected data source specified above.

Password

Enter the password associated with the User Name specified above.

Password Encryption Key Icon

Click the password encryption icon to encrypt your password for this Connection document. You can click it again to turn encryption off. continued

Chapter 4: Defining Lotus Connections 21

Connectivity Field

Description

Selection Type:

Select the desired option. You can choose to connect to data in: Tables Views Procedures (stored procedures) Note When you browse for a Stored Procedure in the Connection document, you are presented with a dialog box listing all the Stored Procedures in the external system database. When you choose a Stored Procedure, the parameters of the chosen stored procedure are automatically listed in the “Parameters” field (see the table below). If you do not specify a Stored Procedure in the Connection document, you can select a Stored Procedure and its associated parameters from the Virtual Field document. In either case, the stored procedure is entered as the default stored procedure in the Events section of the activity document. In most cases returned values are handled by the external system database; in the case of Oracle, the Oracle connector handles returned information. This is transparent to you, however the person responsible for writing Oracle stored procedures should be aware of it. See the Oracle example in Chapter 7 for a full explanation. Note At present, only the Lotus connector for DB2 supports output parameters. Caution Using the “procedures” option with Sybase and OLE DB may cause errors, see “Error When Attempting to Use Stored Procedures in Sybase or OLE DB” in Appendix A for more information.


In the Table/View/Procedure/Subdirectory Selection section of the document you select the specific metadata that you want to access through this Connection. Table/View/Procedure/Subdirectory Description Selection Field Use the Manual button to select a table that does not appear in the current list of tables. After you enter a table all of the associated columns are displayed. See the section below, “Using the Manual Button,” for more information. Owner (Not available in File connection documents)

This option allows you to select from tables by owner name. The default value is , allowing you to select from all tables in the database. Click the down-arrow button to see a list of existing owner names. This enables you to select only from tables belonging to the specified owner.

Name

This field shows the name of the specific table or view you select from the data source. Click the down-arrow button to access a list of the tables or views from which you can choose.

Column(s)/Parameters/File Attributes

This field lists the column names and their associated data types found in the selected table or view of the external data source. If you are working with procedures, this field displays the stored procedure parameters. See “Selection Type” in the table above. If connecting to a file system, use this field to list file attributes corresponding to data types from the selected subdirectory.

Comments

Enter text in this field that may be helpful to you in organizing or keeping track of your connectivity documents.

Using the Manual Button Use the Manual button to specify a table that is not included in the list of tables/views/procedures/subdirectories shown when you select the down-arrow button next to the Name field. You must enter the owner name and the table name (note that in the case of the File connector, there is no owner). You must enter these items exactly as they are named in the data source or DECS will not be able to locate them. Chapter 4: Defining Lotus Connections 23

Completed Connection Document This completes the steps needed to create a Connection document. Below is an example of a completed Lotus Connection document for a Sybase database.


Chapter 5 Virtual Fields Activities This chapter provides an overview of Virtual Fields activities, information regarding preparation of external system fields, and instructions for creating these activities.

Introduction to Virtual Fields Activities DECS activities monitor Notes forms. DECS connects these forms to external data sources (such as DB2) through Lotus connectors. Once a system administrator has created a Virtual Fields activity (previously known as DECS RealTime), Domino users can open, create, update or delete external system data directly and transparently through their Notes Client. By extension, Web clients may open the same Notes form that the activity monitors by accessing a Domino Release 5.0.5 or Domino V6 server, and obtain access to supported external source data. For example, if the external database to be queried or updated from the Notes form is a DB2 database, Notes end-users may work with DB2 data as if it were in Notes. DB2 connectivity software is not required on the client system. Network access to the external data source is handled by the Domino server machine, which contains DECS connectivity software for the external data source, such as DB2. No programming is required to accomplish this functionality. Virtual Fields activity functionality includes features not available in the earlier DECS RealTime activity: support for computed subforms, options for new line delimiters, additional logging support, and support for procedure return parameters following insert and update operations. Output from write operations allows results of write operations to be returned to fields in the Notes document being monitored following insert and update operations. Overview In Virtual Fields activities, Note documents exist for every data set presented to the user. Virtual Fields activities simply add external system data to an existing document.

25

In the simplest Virtual Field scenario, the Notes document contains only the key value necessary to retrieve the external system data. These Notes documents are referred to as “key” documents (in previous documentation these were referred to as “stub” documents). While the Notes document can be a simple key document, it can also contain additional fields. Any field not mapped to external system data is saved in the Notes document. Each Virtual Fields activity monitors a specific Notes form where the metadata is defined. Metadata is the list of fields in the Notes form that are mapped to a list of fields in the external data source during data query or update. You must map the key fields in the external data source to the corresponding fields in the Notes form using the Virtual Fields activity. The Virtual Fields activity requires key documents (referred to as “stub documents” in previous releases) in the Notes database to function. These key documents are initialized by the Virtual Fields activity. See below, “How Key Documents Work,” for more information. In addition, Virtual Fields activities can invoke external system stored procedures to produce the data to display in the form. Multiple Virtual Fields Activities and Monitor Order Virtual Fields activities operate at the field level. You can have multiple Virtual Fields activities monitoring the same form in a Notes document, but each 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 form contains all the fields, but only the fields for the stopped Virtual Fields activities will be blank. In brief, you can use one or more Virtual Fields activities to monitor a form in a Notes document, as long as you make proper 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 summary, one or more external sources may be accessed from the Notes form. A single external data source definition (Connection document) indicates the data source to connect to and the metadata to use. Many Virtual Field activities can be used to monitor a single form; each of these access data from multiple external data sources. In addition, you have the option of storing retrieved data to the Notes form, or simply viewing the retrieved data (see Data Storage under “General Options” later in this document).


Using Key Documents When you initially create a Virtual Fields activity for a database which has existing records, DECS populates the Notes database with one “key document” for each external system record. You, the user, must initialized the keys. It is a one time task that is used to populate a new Notes database with the necessary key documents. These “key documents” contain the key value(s) that are mapped to 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. When the Notes document is opened, the key(s) in the “key documents” are used to fetch external system data to populate the rest of the fields. When you create a new document through a Notes client, a “key document” is created and saved with the key field value(s). In the simplest case, all of the data resides in an external database and the Notes document only holds the lookup key; the document is really a place holder, or key document. However, the “key document” can be much more than just a container to hold the key(s). It can be used to contain other data in addition to the data stored in the external system. Any fields on the form which are not mapped to an external system field in the activity document will be stored in the “key document.” In addition, in the Virtual Fields activity document, mapped fields can be specified as fields that should be saved in the “key document.” In any case, all mapped field values are stored in the external data source. For example, you can construct a form, monitored by a Virtual Fields activity, that displays employee history, payroll data, and personal information. In this situation, assume that the employee data and personal information is stored in a Notes Database (nsf), and the payroll department information is stored in a DB2 database. In this case, the “key document” is only a “key” in the sense that the employee id, for example, is used to fetch the payroll information when the employee’s information document is opened. If the Virtual Field activity were not running, or if the user did not have privileges to the DB2 data, the user would still see all of the information about the employee, but the payroll fields would be blank.

Chapter 5: Virtual Fields Activities 27

Usage Requirements for Virtual Fields Activities There are three usage requirements to keep in mind: •

Indexing

•

Key Field Datatypes

•

HTTP Server

The Indexing requirement is necessary for proper Virtual Fields activity operation, as well as Key Field Datatypes and HTTP Server. Indexing For Virtual Fields, the following fields should be indexed: •

Mapped key fields should be indexed. The column mapped as a key field must be indexed in the external system. See “Key Field Datatypes” below for more information.

Key Field Datatypes Any field used for a key field in a Virtual Fields activity must be usable as a key field in the external system data source. For each of the data sources listed below, the specified data types cannot be used 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 database documentation.

•

OLE DB/SQL Server — IMAGE, TEXT, and NTEXT cannot be used as keys.

•

Notes — RICH TEXT fields cannot be used as keys.

Note Refer to the data source documentation for more information about the use of data types as key fields. HTTP Server When using the HTTP Server to access documents, you should not use the Virtual Fields update event option “Conflict Detection” because it relies on the use of hidden fields and the HTTP Server does not save context information. Performance in Virtual Fields To maximize performance in Virtual Fields activities, when the external Connector is an SQL database, make sure an SQL index exists on the key fields. For example, if the key fields for a Virtual Fields activity monitoring 28 DECS Installation and User Guide

table “MyTable” are “FirstName” and “LastName,“ create an index in the SQL database as follows: CREATE UNIQUE INDEX IndexName on MyTable (FirstName, LastName)

When the Virtual Fields activity is enabled, DECS opens the Connection when the first event for that activity is processed. DECS closes the Connection as soon as possible after the activity has been scheduled to stop. By default, a single persistent Connection is shared by all users of the Notes database. It is possible to set the maximum number of concurrent, opened Connections to increase performance (see Max. Connections options in the Virtual Fields General Options section).

Using the Activity and Connection User Assistant You use the New Activity/Connection User Assistant to create a Virtual Fields activity. The User Assistant prompts you through the steps of creating a Virtual Fields activity. If you choose not to use the User Assistant a blank activity document is displayed, which you can fill in to define the activity. For information about how to fill out an activity document without the aid of the New Activity User Assistant, see the section in this chapter entitled ”Creating an Activity without the User Assistant.“ •

Assistant — Click the following icon on the Administrator to turn the User Assistant on or off:

Turning the User Assistant On When the User Assistant is turned on, it enables an automated step by step process for filling in an activity document. In a Connection document a list of steps appears on the document. The navigator indicates when the User Assistant is turned on or off by displaying the appropriate text:

When you click the Add Activity icon on the action bar, the New Activity/Connection User Assistant starts and steps you through the process of creating an activity.


See the section “Creating a Virtual Fields Activity with the User Assistant” later in this chapter.

Turning the User Assistant Off When the User Assistant is turned off, clicking the Add Activity icon causes a blank activity document to appear. Fill in the fields and select appropriate options in the blank activity document. See the section “Creating a Virtual Fields Activity without the User Assistant” later in this chapter. The navigator indicates when the User Assistant is turned on or off by displaying the appropriate text, as illustrated below:

Establishing Access Control in the Domino Directory In the server document for the DECS server’s Domino Directory (formerly referred to as the Name and Address Book), the “Only allow server access to users listed in the directory” option is set to “Yes” by default. However, to be able to browse the server, set the “Only allow server access to users listed in the directory” option to “No.” The alternative is to make sure that all users who will be creating DECS activities have entries in the Domino Directory and that the server is listed as part of a group. For more information, see the pop-up help in the Domino Directory document.


Creating a Virtual Fields Activity with the User Assistant You can use the User Assistant to create a Virtual Fields activity. When the User Assistant is enabled, it steps you through the process of creating the activity. If the User Assistant is not enabled, clicking the Add Activity icon causes a blank activity document to appear. In that case, see the section “Creating an Activity without the User Assistant” later in this chapter.

Step 1 — Click the Add Activity Icon Click the Add Activity icon.

In either the Activity view or the Favorites view (or a Folder view) click the Add Activity icon in the Action bar. A message box opens containing text that explains the steps the User Assistant will take you through.

If you have not made any selections from the User Assistant, clicking the Cancel button on this message box closes the activity form and returns you to the DECS Administrator. Once you have made one or more selections Chapter 5: Virtual Fields Activities 31

while you are in the User Assistant, clicking Cancel causes the User Assistant to shut down, but the activity document stays open, in Edit mode, displaying the choices you have made up to that point. You can then manually complete the activity document or abandon it. Note Any choices you make while using the User Assistant can be changed later by opening the activity document in Edit mode.

Step 2 — Select the Domino Database A list of Domino databases appears (see illustration below). Select the Domino 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 Domino application (nsf) you want to select. However, if the list is too large to be completely accommodated by scrolling, an overflow message appears at the bottom of the list () and a box appears under the list, which you use to type in the exact name of the table you want to use. Note Immediate or “real-time” monitoring uses the Notes replication ID of the application database. A Virtual Fields activity does not distinguish between the databases that share the same replication ID. Databases have the same replication ID when they are replicas of each other and when one database is created using the operating system to copy an existing database.


Step 3 — Select the Domino Form to Monitor A list of forms within the selected database appears. (These are the forms you will use to display external system data.) Select a single form that you want to monitor from the list shown. Note Use the “Form Override” check box in the “General Options” section of the Virtual Fields Activity document to indicate that the Virtual Fields activity should monitor all forms within the database, regardless of the form it uses. See the section on “Virtual Fields Activity Options” later in this chapter for more information.


Step 4 — Select the Lotus Connection for the Data Source Select the Connection for external data source you want to monitor from those available in the Select Connection dialog box, shown below. Note When the list of tables is large, you can scroll down the list to find the table you want to select. However, if the list of tables is too large to be completely accommodated by scrolling, an overflow message appears at the bottom of the list () and a box appears under the list, which you use to type in the exact name of the table you want to use.


When you have selected a Connection and there is more than one table in the external database, another dialog box opens asking you to select a table in the external database.


Step 5 — Map Data Field(s) After specifying the external data source and providing any required connectivity information, such as User Name and Password, the Data Field Mapping dialog box appears. Use this dialog box to map data field(s) between the Notes application and the external data source.

Note This dialog box also makes it possible for you to map key fields. Virtual Fields and Mapping Key Fields You are prompted to map one or more key fields. The illustration below shows the interface for mapping key fields in a Virtual Fields activity. Caution When you create an activity with the OLE DB Connector, the key field should not be a TEXT, NTEXT or IMAGE datatype. These datatypes cannot be used in an ORDER BY clause or in the WHERE, HAVING, or ON clause, except with the LIKE or IS NULL predicates. Using the UNID as Key Field DECS provides an option to use the Notes universal ID that is created automatically by Notes for each document when a document is created. This makes it unnecessary for you to include an extra field in your Notes front end solely as a key field.


Step 6 — Virtual Fields Activity Events to Monitor Selection After mapping key and data field(s), the Virtual Fields Activity Event Selection dialog box appears. The last required step is to select the event(s) (create, open, update, delete) that you want to monitor. You see this interface only when you are creating or editing a Virtual Fields activity document. Note The events that you are monitoring are on the Notes Form you specified in this activity document, however, when you update, you update to the external system. The user name used to connect to the external system requires read and write permission for that external system. If a user has only read rights, that user can open a document, but cannot update that document and save changes to the external system. The user receives an error message.


Step 7 — Name the Activity Document Next, you are prompted to enter a unique name for this activity. Enter a unique name and click OK.

After you name the activity and click OK, the following informational message box appears outlining your options.

Click OK. The Virtual Fields activity document appears, showing your selections. The numbered User Assistant icons in the document correspond to the major steps the User Assistant uses to create the Virtual Fields activity.


Step 8 — Enable Subforms At this point in the process you can select this option to allow the use of subforms that are controlled by a formula. Subforms that are not controlled by a formula are included by default. If you select this option, a dialog box opens that lets you select the available computed subforms that you want to use. Include only subforms controlled by a formula.

Step 9 — Select Options You can now select the specific options that you want for this Virtual Fields activity. See “Virtual Fields — Options” in this document for a full description. If you select Update, you must also select Open, otherwise the DECS Administrator will not save the activity. You must also perform a one time initialization of keys, see ” Initialize Keys” later in this document for complete information.

Step 10 — Select Scheduling Options Select how you want to control the scheduling of the Virtual Fields activity. The options are Manual, AutoStart, and Custom. See the “Scheduling” section later in this chapter for more information.

Step 11 — Save and Close the Document Choose File - Save to save this Virtual Fields activity definition. Choose File - Close to close the Virtual Fields Activity document and return to the Administrator.


Step 12 — Initialize Keys You must initialize keys once and only once. You must first save the file. Once the file is saved, the “Initialize Keys” button appears in the Action bar. Click the “Initialize Keys” button, now you can close the Virtual Fields Activity document. For more information about Initializing keys see, “Virtual Fields — Initialize Keys” later in this chapter. Note If you have already created “key documents,” do not initialize keys again.

Step 13 — Process the Virtual Fields Activity You can process the activity using the Start and Stop buttons in the Action bar of the Activities view or the Favorites (Folders) view. (When you select “Auto Start” in the Scheduling section of the activity document, the Virtual Fields activity is established each time that the server starts. See the Scheduling section for more information.) Click the Virtual Fields activity to select it and then click the Start button to begin processing it. To stop a Virtual Fields activity, select the Virtual Fields activity and click the Stop button.

Creating an Activity without the User Assistant This section provides information on how to create a Virtual Fields activity without using the User Assistant. In this case, the User Assistant must be disabled in the navigator. When the User Assistant is disabled, clicking the Add Activity icon causes a blank Virtual Fields activity document to appear. Follow the steps below to create a Virtual Fields activity using a blank Virtual Fields activity document.

Step 1 — Click the Add Activity Icon Click the Add Activity icon.

The Virtual Fields activity document appears. The illustration below shows a Virtual Fields activity document.


Step 2 — Enter a Name for the Activity Enter a unique name for the activity in the Name field at the top of the document.

Step 3 — Select the Domino Application and the Form to Monitor Click the down-arrow icon in the “Domino Application” section. A list of databases appears. Select the database that contains the Domino application that you want to monitor. Once you select a database, you are prompted for a form name. Note When the list is large, you can scroll down the list to find the domino application (nsf) you want to select. However, if the list is too large to be completely accommodated by scrolling, an overflow message appears at the bottom of the list () and a box appears under the list, which you use to type in the exact name of the table you want to use. Note Immediate or “real-time” monitoring uses the Notes replication ID of the application database. A Virtual Fields activity does not distinguish Chapter 5: Virtual Fields Activities 41

between the databases that share the same replication ID. Databases have the same replication ID when they are replicas of each other and when one database is created using the operating system to copy an existing database. Note Use the “Form Override” check box in the “General Options” section of the Virtual Fields Activity document to indicate that the Virtual Fields Activity should monitor all forms within the database, regardless of the form it uses. This option is only applicable to Virtual Fields Activity documents. See the section on “Virtual Fields Activity Options” later in this chapter.

Step 4 — Select the Lotus Connection for the Data Source Click the down-arrow icon in the External System section to select from existing Lotus Connection documents. Note When the list is large, you can scroll down the list to find the domino application (nsf) you want to select. However, if the list is too large to be completely visible, an overflow message appears at the bottom of the list () and a box appears under the list, which you use to type in the name of the table you want to use.

Step 5 — Enable Subforms Select this option to allow subforms controlled by a formula to be used. Subforms that are not controlled by a formula are included by default. If you select this option, a dialog box opens that lets you select the available computed subforms that you want to use. Include only subforms controlled by a formula.


Step 6 — Mapping Click the down-arrow icon in the “Mapping” section. The field mapping dialog box appears. Use this dialog box to map the key and data fields between the Domino application and the external data source. Note When you create an activity with the OLE DB Connector, the key field should not be a TEXT, NTEXT or IMAGE datatype. These datatypes cannot be used in an ORDER BY clause or in the WHERE, HAVING, or ON clause, except with the LIKE or IS NULL predicates.

Step 7 — Select Event(s) to Monitor Select one or more events to monitor. Click the down-arrow icon in the Events section. A dialog box appears. Select the document events that you want to monitor.

Step 8 — Select Options and Initialize Keys Select the options, multivalue data options, and the event options you want to enable or specify under the “Options,” “Multivalue Data,” and “Event Options” tabs in the document. See the section “Virtual Fields: Options,“ ”Multivalue Data,“ and ”Event Options: Create, Open, Update, and Event Options“ later in this chapter for more information. You must also perform a one time initialization of keys, see ” Initialize Keys“ later in this document for complete information. If you select Update, you must also select Open, otherwise the DECS Administrator will not save the activity.

Step 9 — Select Scheduling Options Select how you want to control the scheduling of the Virtual Fields activity. The options are Manual, AutoStart, and Custom. See the “Scheduling” section later in this chapter for more information.

Step 10 — Save and Close the Document Choose File - Save to save this Virtual Fields activity definition. Choose File - Close to close the Virtual Fields activity document and return to the DECS activity administrator.

Step 11 — Initialize Keys You must initialize keys once and only once. Do this after you have saved and exited the Virtual Fields Activity document you have just created. Reopen the document and click the ”Initialize Keys“ button, which will now have become available in the Action bar. Once you do this you can close the Virtual Fields Activity document. For more information about Initializing keys see, ”Virtual Fields — Initialize Keys“ later in this chapter.


If you have already created ”key documents,“ do not initialize keys again.

Step 12 — Process the Activity You can process the activity using the Start and Stop buttons in the Action bar of the Activities view or the Favorites (Folders) view. When you select “Auto Start” in the Scheduling section of the activity document, the Virtual Fields activity is established each time that the server starts. See the Scheduling section for more information. Click the Virtual Fields activity to select it and then click the Start button to begin processing it. To stop a Virtual Fields activity, select the Virtual Fields activity and click the Stop button.

Options Overview Once you have specified the Domino application, the Connection you want to use, and set up mapping, there are a number of options for you to consider in setting up the activity. In this document, these options are broken down into the following categories: •

General Options (includes Initializing keys)

•

Multivalue Data

•

Event Options

•

Scheduling Options


General Options The General Options section of the Virtual Fields activity document, illustrated below, presents options that can be applied to an activity regardless of the type of Event the Virtual Fields activity monitors. Each of the General Options is described after the illustration.


General Options

Description

Monitor Order

If you use more than one Virtual Fields activity for a single Notes form, you can specify the order in which the document’s events are intercepted. The monitor order also enables you to use multiple activities that connect to different tables and use values found by the first Virtual Fields activity (monitor order 1) as keys for subsequent Activities (monitor order 2, 3, etc.). Activities with monitor orders of 2, 3, 4, and so on, must monitor an Open event. They may monitor other events too, but one of the events must be an Open event. Depending on the nature of the activity, the activity with monitor order 1 may be required to monitor an Open event as well. When adding or updating data to a source from a document that is not the first in the monitor order, a row is created in the source that may not contain all fields or key values. To include all data and key fields, use one of the following methods:

Max. Connections

This option sets the maximum number of Connections to the external database that can be open to service concurrent user requests simultaneously. DECS opens one Connection to the external data source when the first Notes application event occurs. If two or more events occur simultaneously, additional Connections are made, up to the maximum number of Connections specified by this option. When the maximum number of connections is reached, subsequent events are queued and occur when each preceding event is serviced. Each Connection lasts only as long as necessary to read from or write data to the external data source. While the Connection is persistent, the time required to service each event is minimal and depends on the amount of data being read or written. The maximum number of Connections, therefore, does not need to be that great in order to service multiple events. Set the maximum connections to 2 or 3 and if users experience significant delays, increase this number.

Form Override

The default is to monitor only documents using the form specified in the Notes Application section above. Selecting this option causes the Virtual Fields activity to process the selected events for all the documents in the Notes database that have the same key(s) as the original metadata, regardless of the form. continued


General Options

Description

Filter Formula

An optional Notes formula defining the documents that the Virtual Fields activity will monitor. Use this option to cause the Virtual Fields activity to process only documents that satisfy the specified formula. Note When you set up a Filter Formula, the selected field must also be defined in “Saved Fields” under the Data Storage option (see below). If a document is created that does not match the filter criteria, it is not inserted into the external table (hence, it is not “processed”), instead, it is saved locally in the .nsf regardless of the “Data Storage” setting.

Data Integrity

Prevent data loss — Enable this option to have DECS write an error to the log for any data that is lost as a result of the transfer and terminate the transfer. Allow precision loss — Enable this option to have DECS not report loss of numerical or datetime precision as a result of the transfer. This allows some loss of precision without stopping the transfer. This option is the default. Allow precision loss & truncation of text — Enable this option to have DECS allow precision loss and to truncate text data when necessary to conform to field lengths in the external database. Note that key fields are not truncated. continued


General Options

Description

Trim Trailing Spaces

This option affects any trailing spaces that exist in the Text fields of the external data. Text trimming only occurs when the fields are read from the external source. There are three choices: Trim spaces on all non key fields — Select this setting to trim trailing spaces only from data fields, not from the key fields. (Default) Do not trim spaces on any fields — Select this option to leave trailing spaces in all fields. Trailing spaces may be required to ensure matching of fields between Notes and the external data. Note When data is put into external system fields of fixed length and then retrieved, the Connection with the external system may be lost because the back end has padded the data with spaces to fit the fixed length of the field. If this occurs, use either a variable length field (VARCHAR) in the external system database, or enable the “Trim spaces on all non key fields” option. You will most likely encounter this situation when you use data of type CHAR as a key field for Oracle 7 or 8 systems. When you use a CHAR data type as a key field, Lotus recommends that you use the default setting, “Trim spaces on non-key fields.” Note When using a Virtual Fields Activity that monitors the Create Event, key fields of type character (fixed length) are only effected by the Activity’s trim options when keys are first initialized. While the activity is running, newly created character (fixed) key fields will remain exactly as they are entered when creating the new record in Notes.

New Line Delimiter for Connection

Select the option you want to use to convert the Notes new-line delimiter to a new-line delimiter in another system.

Data Storage

Remove all real-time fields from documents — Enable this option if you want to remove all the data fields mapped in the Activity from the Notes document before it is saved to disk. This is the default. Leave all real-time fields in documents — Enable this option if you want to leave all the data fields in the Notes document, rather than removing them after updating the external source (see above). This option only takes effect when creating or updating a document when the activity is active. Leave selected real-time fields in documents — Enable this option if you want to leave selected data fields in the Notes document. You may want to select this option in order to enable views of the forms. continued


General Options

Description

Saved Fields

This option is only visible if you have selected “Leave selected real-time fields in documents.” Click the down arrow to open a list of Notes data fields from which you can select the data field you want. If you do not select any fields, it is equivalent to enabling the Remove all real-time fields from documents option. Note If you use the Filter Formula option, the selected field must also be defined here in Saved Fields.

Initialize Keys When you are working in a Virtual Fields activity document, there is a button labeled ”Initalize Keys“ in the Action Bar. When you click this button DECS populates the currently selected Virtual Fields activity key fields with data from the external data source for that Connection. This command should be used only once after creating a Virtual Fields activity. Initializing keys again creates duplicates of existing documents. If you have specified Leave Selected Virtual field Fields in Document or Leave All Virtual field Fields in Document, the associated fields are transferred to the Notes application. When using Initialize Keys with a Virtual Fields activity that has a Filter Formula, you are asked if you want to use a conditional clause to restrict the number of external records imported into Notes. If you choose Yes, you are prompted to enter the external conditional clause. The conditional clause must be in the external system’s syntax for a keyed selection clause. For SQL based systems, the conditional clause is that part of a WHERE clause following the word ”WHERE.“ For example, if the complete statement were: SELECT * from Table WHERE Number > 1, you would only enter Number > 1 as the key initialization condition. Note When you create an activity with the OLE DB Connector, the key field should not be a TEXT, NTEXT or IMAGE datatype. These datatypes cannot be used in an ORDER BY clause or in the WHERE, HAVING, or ON clause, except with the LIKE or IS NULL predicates.


Multivalue Data in Virtual Fields The Multivalue Data options allow you to consider non-key fields as multivalue fields. Once selected, there are more options for sorting and ordering for you to choose from. Each Multivalue Data option is described after the illustration.

Multi-Value Data Description Options Multivalue Data

Enable this option to have the Virtual Fields activity consider non-key fields to be multivalues. Multivalue Data allows a single document in a Notes database to relate to multiple records in the Connection. When enabled, the Open event will read all records of the external system which match the key data field(s) and combine the multiple fields data into Notes multi-data fields. The Create and Update events reverse the operation. continued


Multi-Value Data Description Options Subkey Fields

This is an additional key field (for one or more fields) that defines the unique key within a collapsed record. If you choose more than one field, you can order them in any way you would like. For example, if four orders by single customers are collapsed into one document with the customer number as the key, and one order is changed, then the order number is required to ensure that the correct record is updated. In this example, the order number is the subkey and provides a unique identification across the individual external records for this customer when it is expanded back to the external data source.

Sorting

Enable this option to have the Virtual Fields activity sort data within the non-key fields. When enabled, the values within the multivalue data fields will be sorted according to the sequence of the indicated “Sorting fields” and their relationships based on the type of sorting (text, binary and ascending, or descending.

Sorting fields

Sorting key fields that define the order of the data WITHIN a collapsed record. The individual values within the multivalue data field are sorted according to the “Text order” and the “Direction” options. All remaining fields will have their multivalue data appropriately sequenced to preserve their order with those of the sorting field or fields.

Text order

Binary — Sort based on the binary order of the character codes. Recommended. Case Sensitivity — Lower case is sorted before upper case. Case Insensitivity — Case is ignored in the sorting process.

Direction

Ascending – Sorting is done alphabetically from A to Z. Earlier dates are placed before more recent ones; smaller numbers are placed before larger ones. Descending – Sorting is done alphabetically from Z to A. Recent dates are placed before more earlier ones; larger numbers are placed before smaller ones.

Character set

Force data into the selected character set for the purpose of sorting. By default the underlying Connection’s character set is used. To provide a character set, use the corresponding suffix. For example, for LCSTREAMFMT_IBMCP932, use “CP932.” See the appendix in the LSX User Guide for a list of character sets.

Multivalue functionality allows activities to group multiple records with a common key value into a single Notes document. By using multivalue fields, these records can appear, for example, as table data. All records with Chapter 5: Virtual Fields Activities 51

the same grouping key field value(s) are combined (collapsed) until a different key is encountered. (As an example, to capture this information, you could use Designer to create a two-row table on a Notes form and adding multi-value enabled fields for multivalues, with separator options set to ”new line.“) In all DECS activities, a key must be defined as one or more fields, for example, ”JOB“ might be defined as the key field. In this case, the DECS activity document would have ”Key“ value field that is not a unique field. To enable a DECS activity to work with multivalue data, check the ”Multivalue Data“ check box under the ”Options“ section of the DECS activity document. This expands the section displaying additional selections. An important option that allows changes to be written back to an external data source is the ”Subkey fields“ option. This option makes it possible for you to select a unique key to identify this individual record in the external system data. For example, if six employees are combined (”collapsed“) into one document with the job title as the key, and data regarding one employee is changed, then the employee number is required to ensure that the correct record is updated. In this example, the employee number is the sub key and provides a unique identification across the individual external records for this employee when it is expanded back to the external data source. Also note that we have numerous sorting options as well. These options allow us to sort the data contained in our combined (”collapsed") records Finally, be sure to initialize keys. This action (that is, Initializing keys) creates stub documents based on the key field(s) in the DECS activity document. These stub documents serve as data containers after the activity is enabled.

Event Options The monitored events are events that occur in the monitored Notes form that you specified in this activity document. The Create, Open, Update, and Delete sections of the Virtual Fields activity document, provide many options that depend on the type of Event the Virtual Fields activity is monitoring. In a Virtual Fields activity document you must choose which events you want to monitor. The options displayed are specific to the type of event or events you choose to monitor. You must choose at least one event to monitor. Each of the options is described in the illustrations and tables on the following pages. 52 DECS Installation and User Guide

Note If you select Update, you must also select Open, otherwise the DECS Administrator will not save the activity.

Document Create Options When monitoring Document Create Events, several options are available depending on the choices you make. A description of the options follows the illustration.


Create Options

Description

Pre-Create Formula

This option executes a Notes formula language statement before the document data is stored. You can use this option to modify existing fields or to compute values for additional fields. For example: FIELD LASTNAME:=@if(LASTNAME = “”;“NA”;LASTNAME);“” Note If you are connecting to an Oracle external system and you must use a text field(s) of fixed length as a key field(s), use a formula filter to pad the specific field to the correct length. See the Oracle 7 or 8 connector information in Lotus Connectors and Connectivity Guide for more information.

Stored Procedure

This option executes a stored procedure in the external data source to store data that has been entered into the Notes document. The field(s) are supplied to the stored procedure as input parameters. To specify the stored procedure and see the parameters that will be passed to the stored procedure and their order, type the stored procedure name in this field and then press F9. The fields that will be passed to the stored procedure are displayed next to the stored procedure name. In a Virtual Fields activity this includes the specified key field(s). Note Domino/DECS supports stored procedure browsing. Note See Appendix A for error situations you may encounter using Sybase or OLEDB stored procedures that return a result set.

Stored Procedure Output

Enable Procedure Output — This option is available only if a stored procedure has been specified in the “Stored Procedure” field. When this option is selected, it opens up the “Stored Procedure 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 in the external system to the Domino Application (that is, the Notes document). The activity’s key(s) and field(s) are supplied to the stored 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 are displayed next to the stored procedure name. Note At present, only the Lotus connector for DB2 supports output parameters. continued


Create Options

Description

Stored Procedure Output Mapping

Domino Application — Specify the fields in the Domino Application (Notes document) that will receive the stored procedure output. Lotus Connection — Specify the fields from the external system that contain the stored procedure output. The first field from the external system maps to the first destination field, the second external system field to the second destination field, and so on. Note These fields must be specified in the “Mapping” section.

Document Open Options When monitoring Document Open Events, several options are available depending on the choices you make. A description of the options follows the illustration.

Open Options

Description

Pre-open Formula (Virtual Fields only)

This option executes a Notes formula before the document data is retrieved from the external system. This option provide you with an opportunity to compute additional fields or modify existing fields used as key information, thereby altering data selection.

Post-Open Formula

This option executes a Notes formula immediately after data is retrieved from the external system. You can use this option to compute additional fields or modify existing fields. For example: FIELD FIRSTNAME := @if(FIRSTNAME = “Al”;“Albert”;FIRSTNAME);“” Note You should not use Post-Open Formulas when using conflict detection. continued Chapter 5: Virtual Fields Activities 55

Open Options

Description

Stored Procedure

This option executes a stored procedure in the external data source to determine the 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 stored procedure from the drop down list and then press F9. In Virtual Fields, the specified key fields are displayed next to the stored procedure name. For connectors that support procedure output parameters, the key fields (in Virtual Fields activities) are passed as input/output parameters and the other fields are passed as output parameters. Note Domino/DECS supports stored procedure browsing. Note See Appendix A for error situations you may encounter using Sybase or OLEDB stored procedures that return a result set.

Missing External Records (Virtual Fields only)

If no matching external record is found for a document on open, you can choose what the action should be: Create Record — this option creates a new record in the external database. Generate Error — this option generates a Notes error message box. Ignore — this option ignores the fact that there are no matching record and opens the document even though it contains no data.


These fields are visible only if “Stored Procedure Output” in either a Create or an Update event has been selected, see either Create or Update event for more information.


Document Update Options When monitoring Document Update Events, several options are available depending on the choices you make. A description of the options follows the illustration.

Update Options Description Pre-Update Formula

When a Notes document is updated, this option executes a Notes formula statement before the data is saved in the external database.

Stored Procedure

When a document is updated, this option executes a stored procedure in the external data source to update the data related to the document. The field(s) are supplied to the stored procedure as input parameters. To specify the stored procedure and see the parameters that will be passed to the stored procedure and their order, type the stored procedure name in this field and then press F9. The fields that will be passed to the stored procedure are displayed next to the stored procedure name. In a Virtual Fields activity this includes the specified key field(s). Note Domino/DECS supports stored procedure browsing. Note See Appendix A for error situations you may encounter using Sybase or OLEDB stored procedures that return a result set. continued


Update Options Description Stored Procedure Output

Enable Procedure Output — This option is available only if a stored procedure has been specified in the “Stored Procedure” field. When this option is selected, it opens up the “Stored Procedure 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 in the external system to the Domino Application (that is, the Notes document). The activity’s key(s) and field(s) are supplied to the stored 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 are displayed next to the stored procedure name. Note Only the Lotus connector for DB2 supports output parameters.

Conflict Detection

Check External Data for Changes — This option ensures that the external data has not changed since the Notes document was opened. If it has changed, an update to the external data source will fail. If this option is enabled and if you make changes to data in a Notes document and then save the document, you must exit 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. Note In a Virtual Fields activity, if you turn on “Conflict Detection” and you connect to a Sybase system, the Sybase database table must be indexed.

Field Level Updates

Only Update Changed Fields — This option causes the Virtual Fields activity to not update fields in the external data source unless the corresponding fields in the Notes document have been edited. Use this option if you have triggers in the external system that monitor updates to individual columns of a table.

Key Field Updates

The following three settings are available for key field updates: Block — Do not allow updates to key fields in the Notes document or the external data source records. Delete/Insert — Updates to key fields will cause the original record in the external data source to be deleted and a new record with the new key added. Ignore — Do not update the key fields in the external data source. If a key field is edited, the change will be stored with the Notes document but the key field(s) in the external data source will not change. continued


Update Options Description Stored Procedure Output Mapping

Domino Application — Specify the fields in the Domino Application (Notes document) that will receive the stored procedure output. Lotus Connection — Specify the fields from the external system that contain the stored procedure output. The first field from the external system maps to the first destination field, the second external system field to the second destination field, and so on. Note These fields must be specified in the “Mapping” section.

Document Delete Options When monitoring Document Deletion Events, several options are available depending on the choices you make. A description of the options follows the illustration.


Deletion Options Description Pre-Delete Formula

Notes formula language statement to execute on the Notes document immediately prior to the deletion in the external data source. Here is an example that sends an email containing information about a deleted document: FIELD LASTNAME:=LASTNAME; FIELD FIRSTNAME:=FIRSTNAME; @MailSend(“John Q Public”;“”;“”;“Doc Deleted”;“Doc deleted from MyDatabase w/ Firstname/Lastname of:”;FIRSTNAME:LASTNAME);“” Note It may be necessary to specify that activity data be saved in the Notes document; otherwise, the specified formula may access the field values after they’ve been deleted. If this were the case for the example above, FIRSTNAME and LASTNAME would be empty. To specify that activity data be saved, in the General Options section of the activity form go to “Data Storage,” choose one of the options “Leave all/selected realtime fields in document.”

Stored Procedure

When a document is deleted this option executes a stored procedure in the external data source to remove the data related to the 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 stored procedure from the drop down list and then press F9. In Virtual Fields, the specified key fields are also displayed next to the stored procedure name. For connectors that support procedure output parameters, the key fields (in Virtual Fields activities) are passed as input/output parameters and the other fields are passed as output parameters. Note Domino/DECS supports stored procedure browsing. Note See Appendix A for error situations you may encounter using stored procedures that return a result set with Sybase or OLEDB.


These fields are visible only if “Stored Procedure Output” in either a Create or an Update event has been selected, see either Create or Update event for more information.


Scheduling This section of the document lets you chose what kind of scheduling you will use for the Virtual Fields activity. A description of the options follows the illustration.

Option

Description

Scheduling Option

Manual — Select this option to manually control the activity using the Start/Stop action bar buttons (available only in the Activity and Folder — Favorites, and so on — views). Auto Start — Select this option to automatically establish this Virtual Fields activity each time the server starts. The activity continues until the server is shut down. The activity’s running state can be overridden using the Start/Stop action bar buttons (available only in the Activity and Folder — Favorites, and so on — views). Custom — Select this option to specify at what time and on which days the activity should run. When you select this option, the “Run Time” and “Run on Days” fields are automatically displayed (these fields are hidden for Manual and Auto Start). The activity starts at the beginning of the specified run time and stops at the end of the specified run time. This option can further be controlled by selecting the days on which the activity should run. The activity’s running state can be overridden using the Start/Stop action bar buttons (available only in the Activity and Folder — Favorites, and so on — views). Note If the activity is started with the action bar’s start button, the custom schedule is completely overridden, which is to say, it will not stop at the end of the specified run time.


Virtual Fields Activity Logging Logging information is available in DECS in the Activity and Folder — Favorites views. Logged information about DECS operations is available to you when you highlight the activity and click the Log button in the action bar.

The log lists the time and date when a Virtual Fields activity started and ran, and information about any errors that occurred during processing of the activity.


Chapter 6 Building a Domino Application This chapter provides information about building a Domino application for use with a Virtual Fields activity.

Building a Domino Application for a Virtual Fields Activity The Domino application being monitored by a Virtual Fields activity must include data fields that map to data fields in the external data source. In addition, the Virtual Fields activity must include at least one field that maps to a key field in the external data source. A key is one or more fields that are used to uniquely identify the data. A Virtual Fields activity can include multiple key fields. The next section gives an example of a Domino application that could be used with a Virtual Fields activity.

63

Example Application Shown below is an application that monitors employee information in an external data source.


Example of the Application Design View The illustration below shows the Design view of the example application. In this application there are labels next to the data fields; these data fields map to the data fields in the external data source, see the illustration below. Note The Virtual Fields activity will map these fields to the fields or columns in the external database.

Chapter 6: Building a Domino Application 65

Virtual Fields Activity Example Shown below is an example of a Virtual Fields activity that uses the example application. The field mapping in the Mapping section of the document maps to the example Domino application above. Note The key fields must be initialized in the Domino application in order for the Virtual Field activity to retrieve the associated information from the external database. You may choose to initialize key fields for the Virtual Fields activity by selecting “Initialize Keys” from the Action menu or clicking the “Initialize Keys” icon.


Running the Virtual Fields Activity Once you have developed a Domino application form and created a Virtual Fields activity, you are ready to run the activity. Note Make certain you have initialized keys. Select the activity and click on the “Start” icon. Press F9 until the activity icon shows that it is running. •

To view a document, open the Notes view that displays the key for documents whose form you are monitoring and click on one of them. When the document opens you should see data that is fetched from the external database.

•

To update a document, open the Notes view that displays the key for documents whose form you are monitoring and click on the document you want to update and change the values as needed. Save the document. The changes will be reflected in the external database.

•

To delete a document, open the Notes view that displays the key for documents whose form you are monitoring and select the document you want to delete and press Delete. The changes will be reflected in the external database.

•

To create a document, open the Notes view that displays the key for documents whose form you are monitoring and choose Create from the Main menu and fill in the fields. Then save the document. The changes will be reflected in the external database.

The next chapter describes options that you can use to refine a Virtual Fields activity.

Chapter 6: Building a Domino Application 67

Chapter 7 Using Virtual Fields Activity Options This chapter provides examples of Virtual Fields Activities that utilize the options available in the Virtual Fields activity document. It covers these topics: •


•


•

Using the Monitor Orders Option

•

Using Stored Procedures in Sybase/SQL

•


•

Using an Oracle Stored Procedure

Using the Options in a Virtual Fields Activity Document This section provides examples of Virtual Fields Activities that utilize the options available in the Virtual Fields activity document. It covers these topics: •


•


•

Using the Monitor Orders Option

•

Using Stored Procedures in Sybase/SQL

•


•

Using an Oracle Stored Procedure

Using Filter Formulas This section provides examples of how you would use the Filter Formula option in conjunction with the Monitor Order option to achieve specific results. Note If a document is created that does not match the filter criteria, it is not inserted into the external table (hence, it is not “processed”). Instead, it is saved locally in the .nsf regardless of the “Data Storage” setting. 69

Saving Data to an External Data System Scenario: Suppose you want to store data from a Notes document in an external data system, such as a DB2 or Oracle database, when the document data becomes 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 activity that monitors the Notes application. In the Virtual Fields activity, you would use a filter formula that includes only documents that have been marked “Published.” At that point the information from the Notes document will be written to the DB2 database, where it would be available to other applications. Any documents that are still “under review” will not be stored in DB2.

Accessing Different External Sources using the Same Notes Application Scenario 1: Suppose you want to use a single Notes front end to interact with information that is potentially in two different tables. For example, the North East 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 region with different external data sources, but using one Notes document as the front end. You could use a filter formula that would detect the region of information and the account request and go to the appropriate external system data. Scenario 2: Suppose that you have two product catalogs in different databases, but you want to present the data through the same front end Notes application. You want to use a single Notes front end, but dependent on a field, you want to control where the data is coming from. Set up identical Virtual Fields activities monitoring a single Notes application, but have each Virtual Fields activity use a filter formula to handle part of the request.


Using Data Storage Options This section provides some examples of how and when you would use the Data Storage options in Virtual Fields Activities.

Building Views Any data that you want to use when building views must reside in the Notes document. Use the option “Leave selected real-time fields in documents.” When you select this option, you can choose the fields that you want to reference in a view from the list of available fields.

Storing a Static Copy of External Data If you want to store a static copy of the external data, you would select “Leave all real-time fields in documents.” Note that if the external data changes, the data in the document is not updated until the document is reopened.

Using the Monitor Orders Option In this scenario, assume that the external data for your Notes Human Resources Information system is in multiple tables. A “join” of the data is required to tie these various tables together to populate the single Employee Information form in the Notes application. In some cases, a join from the database may not be possible, because the tables may reside in different databases (one in Oracle, one in Sybase, for example). Information in the Employee Information form includes Employee Name, Department Name and Location Information. The following table explains which fields are used from which table and how they will relate to the Notes form. Fields Used: Employee Information EMPLOYEE Form Table EmpID

EmployeeID

EmpName

EmployeeName

DepartmentNo (may be hidden)

DeptNo

DEPARTMENT Table LOCATION Table (access with monitor (access with monitor order 3) order 2)

DeptNo

Department

DeptName

DepartmentLoc (may be hidden)

DeptLoc

Location

LocCode LocName …

Chapter 7: Using Virtual Fields Activity Options 71

How to Configure: To do this join, you will create three Virtual Fields activities that each monitor separate tables: one to monitor the Employee table, one to monitor the Department Table and one to monitor the Location Table. The first activity (using a Monitor Order of 1) will provide data that will be used by the other activities (with Monitor Orders of 2 and 3) as “keys” to their tables. The Notes Form “Employee Information” will need to contain those fields 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 the Notes application to these secondary tables, select the Option “Leave selected Virtual Fields fields in Documents” and list all the fields which are used as keys to the external system (DeptmentNo, DepartmentLoc). Note Activities with monitor orders of 2, 3, 4, and so on, must monitor an Open event. They may monitor other events too, but one of the events must be an Open event. Depending on the nature of the activity, the activity with monitor order 1 may be required to monitor an Open event as well. 1. Create a Connection document for each of the external data sources: one for the employee table, one for the department table, one for the location table. 2. Create a Virtual Fields activity based on the Employee Information Form and the Employee Table. Select all fields that will be used by the form and/or used as a key to another field. In this case, select at least the following: EmployeeName, DepartmentNo. Notes

Employee Table

EmpID as the key

EmployeeID as the key

DepartmentNo

DeptNo

3. Create a second Virtual Fields activity based on the Employee Information Form and the Department Table. Select the following fields: Notes

Department Table

DepartmentNo as the key

Deptno as the key

Department

DeptName

Caution Set the Monitor Order for this activity to 2. This allows the first activity to retrieve the information from the employee table before looking into the department table for the DeptName field.


4. The third activity works like the second, except it monitors the Location Table. It will use a monitor order of 3 because its lookup depends on information provided by the second Activity. Notes

Location Table

DepartmentLoc as the key

LocCode as the key

Location

LocName

Using Stored Procedures in Sybase/SQL This section provides an example of a Virtual Fields activity that uses stored procedures with a Sybase external data source or a SQL (using Sybase) external data source. Preliminary Setup Sybase and OLEDB normally return a result set from a stored procedure, which DECS “sees” as if it were a result set from a table or view. Because of this, when setting up an Activity using a Stored Procedure, you must do the following: 1. Create the DECS Sybase Connection Document by selecting table, not procedure. 2. Use or create a table containing the exact column names returned by the stored procedure, and use this in the mapping process in the DECS Activity. 3. Identify the stored procedure to use in the Activity Options under the appropriate “When Intercepting a document” section. There are separate sections for the Open, Create, Update, and Delete events, and separate stored procedures are needed for each event to perform functions specific to that event. When DECS is activated, the stored procedure is used, overriding the field mapping. Note For additional information, see “Stored Procedures in Sybase or OLEDB” in the Appendix.

Sybase/SQL Stored Procedure Example In this example there are four stored procedures for the table addrbook in Sybase. When using these stored procedures, the key fields used must be FirstName then LastName, and the mapped fields must be (MailDomain, MailServer, MailAddress, CompanyName, and State). The stored procedures, table name and fields must use the correct case since Sybase is case sensitive.


To use a stored procedure, enter the name of the stored procedure in the options section for the appropriate event in the Virtual Fields activity document. In this example, these would be: Create: QEInsertaddrbook Open: QESelectaddrbook Update: QEUpdateaddrbook Delete: QEDeleteaddrbook The following illustration of a Virtual Fields activity document shows how these stored procedures are entered in the Stored Procedure fields of the corresponding document event options. The next section, “Testing the Stored Procedures in Sybase/SQ,” contains an example of how you can test the stored procedures directly in SQL through the database client.


If you use stored procedure output parameter mapping, be sure to fill in the fields on the activity form. The illustration below shows the output parameters fields filled in.

Testing the Stored Procedures in Sybase/SQL The examples below show how you would execute the stored procedures in SQL through the database client, in this case Sybase. You can test that the stored procedures work properly by executing them directly as shown below. execute QEInsertaddrbook ’OurDomain’, ’ThisServer’, ’OurAddress’, ’Open Research’, ’NH’, ‘Adelino’, ’Fontes’ execute QESelectaddrbook ‘Adelino’, ’Fontes’ execute QEUpdateaddrbook ’OurDomain’, ’ThisServer’, ’OurAddress’, ’Open Research’, ’NH’, ‘Adelino’, ’Fontes’ execute QEDeleteaddrbook ‘Adelino’,’Fontes’ Stored Procedure Definitions Below are the actual stored procedure definitions used in the preceding example. Note that these are Sybase procedures; stored procedures for other 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( @FirstName varchar(20), @LastName varchar(20) )

as select FirstName,LastName, MailDomain, MailServer, MailAddress, CompanyName,State from addrbook WHERE FirstName = @FirstName and LastName = @LastName create procedure dbo.QEUpdateaddrbook( @FirstName varchar(20), @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( @FirstName varchar(20), @LastName varchar(20) )

as DELETE FROM addrbook WHERE FirstName=@FirstName and LastName=@LastName

Using a DB2 Stored Procedure A DB2 stored procedure may be used wherever procedures are allowed in a Virtual Field activity and within an LSX script. The stored procedure being called must have its parameters set up correctly for the call. Input and output values are provided to DB2 procedures as named parameters. This requires that the parameters in DB2 use the same names as the fields being provided as the parameters unless explicitly mapped in the activity. The parameters being provided include key values when being used in the context of a keyed operation (selection, update, or delete contexts), and data values when relevant (insert or update contexts). The DB2 parameter data types should be selected as the closest match to the data type in the LC API. Any result set output from a DB2 stored procedure must be returned through a DB2 cursor left open in the stored procedure. The result set in this cursor will become the result set produced by the stored procedure. The DB2 Connector supports the return of output parameters from stored procedures. The following scenarios describe what is returned from a stored procedure call: •If the stored procedure returns a result set only, the Connector will return that result set fieldlist. • If the stored procedure returns multiple result sets, the Connector will return the first result set fieldlist only. • If the stored procedure returns output parameters only, the Connector will return a fieldlist of those output parameters. • If the stored procedure returns output parameters and a result set, the Connector will return a fieldlist of the output parameters only.


• If the stored procedure returns output parameters and multiple result sets, the Connector will return a fieldlist of the output parameters only. The DB2 Connector will not return multiple fieldlists in any scenario and a fieldlist of output parameters will always have return precedence. Stored procedure in DB2 can be written in Java, C, and C++. DB2 Universal Database versions 6.1 and 7.1 provide a Stored Procedure Builder with which to create procedures easier. The version 7.1 Builder also allows stored procedures in SQL. Below is an example of a simple SQL stored procedure. CREATE PROCEDURE DB2ADMIN.NEW_SALES_ORDER ( IN CUSTID int, IN ITEMID int, IN QTY int, OUT SONUM bigint) LANGUAGE SQL P1: BEGIN DECLARE CUSTVAR int; DECLARE ITEMVAR int; DECLARE QTYVAR int; DECLARE ITEMCOSTVAR dec(7,2); DECLARE AMTVAR dec(9,2); DECLARE STAMP timestamp; DECLARE cursor1 CURSOR FOR SELECT ITEMCOST FROM DB2ADMIN.ITEMS WHERE ITEMID = ITEMVAR; DECLARE cursor2 CURSOR FOR SELECT SONUM FROM DB2ADMIN.SALES_ORDERS WHERE DTEORD = STAMP; SET CUSTVAR = CUSTID; SET ITEMVAR = ITEMID; SET QTYVAR = QTY; SET STAMP = CURRENT TIMESTAMP; OPEN cursor1; FETCH FROM cursor1 INTO ITEMCOSTVAR;


CLOSE cursor1; SET AMTVAR = QTY * ITEMCOSTVAR; INSERT INTO DB2ADMIN.SALES_ORDERS (CUSTID, ITEMID, QTY, AMT, DTEORD) VALUES (CUSTVAR, ITEMVAR, QTYVAR, AMTVAR, STAMP); OPEN cursor2; FETCH FROM cursor2 INTO SONUM; CLOSE cursor2;

END P1

Using an Oracle Stored Procedure An Oracle stored procedure can be used in a Virtual Fields Notes activity or with an LC LSX script. However, the stored procedure being called must have its parameters set up correctly for the call. When you browse for a stored procedure in the Connection document, you are presented with dialog box listing all the stored procedures in the external system database. When you choose a stored procedure, the parameters of the chosen stored procedure are automatically listed in the Connection Document. If you do not specify a stored procedure in the Connection document, you can select a stored procedure and its associated parameters from the Virtual Fields activity document. In either case, the stored procedure is entered as the default stored procedure in the Activity Events that you selected in the stored procedure field, followed by its list of parameters. In most cases returned values are handled by the external system database, in the case of Oracle, the Oracle connector handles returned information. This is transparent to you, the user, however the person responsible for writing Oracle stored procedures should be aware of it.

Input Values and Named Parameters Input values are provided to Oracle procedures as named parameters. This requires that the parameters in Oracle use the same names as the fields being provided as input values. The inputs being provided include key values when they are used in the context of a keyed operation (selection, update, or delete context), and data values when relevant (insert or delete context). The input value data types provided by the Oracle connector are selected as the closest match to the data type in the DECS system, and will Chapter 7: Using Virtual Fields Activity Options 79

be converted by Oracle to the procedure parameter defined data types, as long as the conversion is supported by Oracle.

Output Parameters Oracle differs from other RDBMS connectors in that there is no way to return a result set from a procedure. Therefore, the Oracle connector supports output parameters as a way of returning results from a stored procedure. This requires additional information to be available at the time the procedure is called, specifically the context of the call and the output parameter names. This information will be automatically provided by Virtual Fields activities, but must be manually specified when calling Oracle procedures from an LC LSX script. The context indicates whether the procedure should expect and specify output parameters, and the parameter names are provided as a property of the procedure call request to the Oracle connector. The output parameters must be standard data types rowsets may not be returned. This restricts the result set from an Oracle procedure to a single row. Any parameters that are indicated as input parameters and are also in the output parameter list will be provided as input/output parameters. The following is an example of an Oracle stored procedure body. This is the format that would be required for the Open event of a Virtual Fields Notes activity assuming that the key field is called NUMBER1 and the data fields are called NUMBER2, TEXT1, and TEXT2. In this context, the key field is the input parameter, and the result set is expected to include the data fields and the key field. To accommodate the fact that one of the output parameter names is the same as a key value in the select statement, the parameter keys should be copied to local variables to avoid scoping problems in the procedure. (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 80 DECS Installation and User Guide

WHERE t.NUMBER1 = number1_request; END; END;


Chapter 8 Virtual Fields and Dynamic Queries This chapter provides information on how to use DECS to create Virtual Fields Activities that enable dynamic, on-demand queries to external data sources.

Overview of Virtual Fields Dynamic Queries The DECS Virtual Fields activity enables a Domino database form to provide direct access to external data sources supported by DECS. The Virtual Fields activity form requires that one or more key field values be held in common with the Notes form (accessed by the Notes client or Web browser client) and the external system. It is the key field(s), entered into the Notes form, that controls the query of the external data. Normally, the Virtual Fields activity requires that the key field(s) exist in the Notes key document (that is, a document containing nothing but a key field) as well as the external data source. In this configuration, the Notes or Web client would open the form that has the appropriate key field value you want to use to query additional external data. There are, however, many situations where the key field value will not already be available within a Notes document. In such cases, clients want to freely insert the key value when they open the Notes forms. The Virtual Fields activity can be set to allow Web and Notes client end users to open Notes application forms and enter key values to Notes form fields then dynamically trigger DECS. These entries are then sent via the Domino DECS server to query the external data source. As an example, a customer with a package tracking number opens a Notes form using a Web browser, enters the tracking number to the Domino server Web form, then, using a button on the form, submits the new document to the Domino server. The button causes the document to be saved and then reopens the new document. Virtual Fields activity detects the open event and uses the tracking number to query the source database, which locates the package information using the tracking number as a key. The matching record results are inserted into the Notes document and sent back to the client Web browser, which displays the status of the package, in real time.

83

The next sections provide information required for defining the Virtual Fields activity and preparing Notes application forms to accept dynamic data queries from Web clients and Notes clients.

Virtual Fields Dynamic Queries from Web Clients This section provides information about using your Web client to invoke a Virtual Fields activity that accepts a key value input for querying an external data source. This extends the functionality of the Virtual Fields activity to provide a dynamic query capability.

Overview of Steps 1. Create a Notes application form that defines the format of the data to be returned to end-users when the query is processed. (This is what is to be displayed to the user accessing the Domino server through a Web client.) This form includes the fields that you want populated from the external system database. Also include one or more key fields, in which the user will enter values to be used to locate the correct external data. The appearance of the application form may be improved by using the Notes form design option of the “Hide paragraph when…” property box. In the example, the form is broken into three primary sections. The top of the form is always displayed. The input field, input help, and “Locate” button only display when the document is in Edit mode. The data fields only display when the document is in read mode. In our example, the key field is “PackageID”. 2. Next, include one hidden field in the form: $$Return field - A computed for display only field of type “text” that specifies the URL for the new document returned once the query data has been input and “Locate” button has been selected. 3. Within the overall Web application, create a URL link to the application form (for more information on specifying URLs to Notes databases and forms, see the Notes Application Developer’s Guide). In our example, we provide an “About” page for the database that contains the URL link for the application form. 4. Define a DECS Virtual Fields activity that monitors the Notes database and the form defined in step 1 above. This form should include the key and data fields you defined in step 1 above.


5. Access the Domino Lookup form from a Web browser. Type in a tracking number (PackageID field). When the Locate button is selected, the document is saved in the database and the $$Return text is passed to the Domino HTTP process. This results in the new document being re-opened. The Virtual Fields Notes Connection is activated, taking the key value, from the PackageID field, submitted in the form. The PackageID value is then sent to the external system, and the table records are searched according to the PackageID value. Results of the search are sent back through DECS and inserted into the document. The document is then sent from the Domino server to the Web client as directed by the URL specified in the $$Return field. What is visible in the form Using the “Hide paragraph when…” properties, different sections of the form appear under different conditions. See the illustration below as you read the following bullets. •

Section 1 is always displayed.

•

Section 2, including the input field, the button, and the help text, only appears when the document is in Edit mode.

•

Section 3 is always hidden. The Domino server only references it.

•

Section 4 is error text. It is displayed when the document is in Read mode and, referencing the “status” field, when no data has been inserted into the document from the Virtual Fields activity.

•

Section 5 contains the data inserted by DECS and only displays in Read mode and, once again referencing the “status” field, when data exists.

Chapter 8: Virtual Fields and Dynamic Queries 85

Example of Virtual Fields Dynamic Queries from Notes Clients Refer to the illustration on the next page as you follow these steps. It is assumed that there is a Notes view sorted on the Virtual Fields key (or that there is a column formula if you use more than one key field). This key or formula value will be used in place of the bold italicized text in step 4. This example uses a single key field called DocKey. 1. Edit your Notes form. 2. Identify the Virtual Fields key(s) field. 3. Add a button to the Notes form. 4. Add the following formula to the button. 86 DECS Installation and User Guide

@Command([FileSave]); @Command([FileOpenDatabase]; @DbName; “Keys”; DocKey); @Command([OpenDocument]) Note Substitute your view name for the “Keys” text in the above formula. Substitute the Virtual Fields key you are using for the “DocKey” text in the above formula (or formula text if you use more that one key). Note that the text you use in place of the “DocKey” text must match the key or column formula of the view. This button is used to reference the view represented by the “Keys” text in this example. 5. Optionally, you can use hide formulas to make the button and key field(s) display when composing a new document and all fields display when opening an existing document. 6. Save the form. 7. With Virtual Fields running, compose a document. Clicking the button will save the document with the new key and reopen it, displaying the Virtual Fields data. This has an added side effect of allowing the user to jump back to compose the form and change the key. Pressing the button locates a different document.

Chapter 8: Virtual Fields and Dynamic Queries 87


Appendix A Configuration and Troubleshooting This appendix provides information about INI variables, error messages, and known problems that you may encounter under certain conditions while using DECS.

NOTES.INI Variables The following entries may be added to the notes.ini file to control DECS: DECSTranslation: This controls text translation, allowing the user to increase performance in exchange for certain assumptions about the data being accessed. Note that none of these settings affects translation between Unicode and other character sets, since it is always required. There are three valid numeric settings: 0 Do not perform translation between character sets (except Unicode). This is valid when all data being accessed is compatible with the Notes LMBCS character set — primarily ASCII printable characters. 1 Do not perform translation between non-LMBCS (and non-Unicode) character sets. This is valid when all data being accessed, except for Notes LMBCS data, is in compatible character sets. 2 Always translate between any character sets. This is the default. DECSNativeText: This allows the local machine’s native character set to be overridden. There are various situations when the native character set is used within DECS, and some back-end systems always consider client data to be in the native character set. Setting this value to a valid text format string replaces the character set obtained from the operating system by DECS with the indicated character set. Appendix D of the LSX LC documentation (LSXLCDOC.NSF) lists the supported character sets. Use the text that remains after removing the “LCSTREAMFMT_” prefix. For example, Code Page 932, represented by the constant LCSTREAMFMT_IBMCP932, would be set as follows: DECSNativeText=IBMCP932. RTMaxEntries: This functionality has been added to DECS to allow support for more than 128 concurrent activities. To increase the maximum number of realtime activities which can run concurrently, add “RTMaxEntries=” to 89

the notes.ini file and assign it an integer value to indicate the new upper limit. If a line already exists, edit its value to the new setting. The lower limit is 128 active activities; a value less than 128 will not change the limit below 128. If the number of activities started exceeds the specified value in the notes.ini file, DECS displays a warning message and subsequent activities will not be started.

Configuration and Troubleshooting This sections provides information about INI variables, error messages, and known problems that you may encounter under certain conditions while using DECS. It consists of the following topics: •

NOTES.INI Variables

•

Security Issues

•

Considerations When Domino/Notes is installed as an NT Service

•

Using DECS Virtual Fields Activities in a Clustered Domino Server Environment

•

Error When Attempting to use Stored Procedures in Sybase or OLEDB

•

Unable to Access Data After Upgrading

•

Error Messages

Security Issues Browsing or running a LotusScript agent that makes use of the Lotus Connectors extensions (lclsx), such as the Initialize Keys utility (run when you click “Initialize Keys”), requires use of operating system level functions to access files and/or external database clients. To do this the agents must have permission to run as unrestricted agents. Solutions If you are using DECS: •

Add the ID “Enterprise Connection Products/Notes Companion Products” to the “Run Unrestricted Agents” field in the Domino Server's entry in the Domino Directory containing that server. This field is found under the Security tab.


•

Resign the DECS Administrator database with a Notes ID which already has permission to run unrestricted agents. Resign the DECS Administrator through the Domino Administrator client, not through the normal Notes client.

If you are writing LotusScript code that uses the LC LSX (Lotus Connector LotusScript Extensions) against the Notes or File connectors •

Agents or other LotusScript code, which uses the Notes or File connectors, must be signed with a Notes ID that has permission to run unrestricted agents. This also applies to any script libraries used by this code. Specifically, connections through these connectors will be blocked with an error unless the signing Notes ID has permission to run unrestricted agents.

Considerations when Domino/Notes is Installed as an NT Service When a Notes/Domino Server is started as an NT Service, Notes/Domino users cannot access Database/Directory Links which are at locations other than the local NT Server. Applications installed as a Service begin execution before the user is prompted to log in at the NT Server. Therefore when Notes/Domino starts up and it is installed as a Service, any mapped drives that the NT Server may have set up are not yet reconnected at the point when the Notes/Domino Server is started. Notes/Domino Server will only recognize drives that are available when it is first started, and any drives that are mapped after Notes/Domino server has started are not recognized. Therefore any directory/database links that point to mapped drives on other computers will not function properly if Notes/Domino Server is started as a Service. The solution for this set of circumstance is to not install Notes/Domino as a Service. When Notes/Domino is not installed as a Service, but is Launched from the “Start Menu” or from a Desktop Shortcut, a user must be physically logged in at the NT Server, because the user has to log in at the server, all Network drives mappings will have been established be when the Notes/Domino server is launched and any directory/database links that are beyond the local server function correctly.

Appendix A: Configuration and Troubleshooting 91

Using DECS Virtual Fields Activities in a Clustered Domino Server Environment DECS Virtual Fields activities can be used to great advantage in a clustered Domino server environment. This brief overview of how replication works in a clustered Domino server environment will help you to understand how DECS Virtual Fields activities take advantage of a clustered configuration. Refer to Domino documentation for information on how to set up clustered Domino servers. When using DECS Virtual Fields activities with clustered Domino servers DECS must be installed on each server and identical RealTime connections and activities must exist in each DECS administrator and be enabled. DECS Virtual Fields will then intercept events in the monitored Domino forms and perform the requested read, write, updates or deletes on the external database. Caution DECS is not currently supported on more than one server of partitioned Domino servers.

Domino Replication Domino replication keeps copies of a database up to date with one another when they reside on different servers. Domino Replication is managed by a process on one designated server which synchronizes the databases on the others. Domino Replication in a Clustered Environment Clustered replication works by a process on each of the Domino servers in the cluster, monitoring databases on the server for changes, keeping a queue of these changes in memory, and calling the replication routines to push those changes to other clustered servers with replication copies of the database. If one or more of the target clustered servers is down, the source server will retry at increasing intervals until it is successful. If the source server crashes, the queue in memory is lost. Lotus recommends that clustered replication be supplemented by periodic scheduled replication, so that the scheduled replication will pick up changes that may be lost if a server crashes. Note that a cluster replicator must be running on all servers to push changes in all directions. There is no “Pull” in cluster replication. The processes involved are pushing, receiving, and indexing.


DECS Virtual Fields Activities in a Clustered Environment DECS Virtual Fields works by loading a management module for each process through the ExtMgr_AddIn parameter in the notes.ini. This intercepts database operations and, when DECS Virtual Fields activities have been started, address real-time requests through operations on the external database. To operate correctly, DECS Virtual Fields activities must be started from the DECS administrator on all servers to intercept real-time events in all replicas. When this is done, DECS Virtual Fields intercepts both the Domino database read on the source server and the database write on the Domino target servers. To prevent unwanted duplication of inserts, updates or deletes to the external database when the Domino databases are replicated from clustered server to clustered server, DECS Virtual Fields will add additional information to the records as they are replicated to indicate that the requested action has already been done. This information does not alter the documents in anyway. Note For DECS Virtual Fields to work as expected on clustered Domino servers the DECS Virtual Fields activity and Connection documents must be identical on all the servers. The least error-prone way to do this is to copy and paste from one to another. It is also recommended that after you paste the documents, you should open the documents for editing and save them to ensure all computed fields are correct.

Stored Procedures in Sybase or OLE DB When attempting to create a DECS Activity that uses stored procedures in Sybase or OLE DB, you may find that the fields cannot be mapped, and the following error displays: “Both the notes and connection data field list must contain at least one value.” The Procedure can be selected, but the Activity cannot be completed or saved.


Solution Sybase and OLE DB normally return a result set from a stored procedure, which DECS recognizes as if it were a result set from a table or view. Because of this, when setting up an Activity using a Stored Procedure, you must do the following: 1. Create the DECS Sybase Connection Document by selecting Table, not Procedure. 2. Use or create a table containing the exact column names returned by the stored procedure, and use this in the mapping process in the DECS Activity. 3. Identify the stored procedure to use in the Activity Options under the appropriate “When intercepting a document” section. There are separate sections for the Open, Create, Update, and Delete events, and separate stored procedures are needed for each event to perform functions specific to that event. When DECS is activated, the stored procedure is used, overriding the field mapping. Example of how to set up an Activity with Sybase using Stored Procedures: In the following example, assume that you have a Notes form with two fields, Key1 and Lastname, and that you have Sybase table(s) with many fields. In addition, assume you have a stored procedure that accepts one input parameter and returns a result set with Key1, Lastname columns. Finally, assume that you have an activity that returns data based on the Open event. You will need to create a Sybase table, a stored procedure, and set up a DECS activity. The Sybase Table First, create a Sybase table (for example dbo.proctable) that has columns made up of what you are ultimately mapping (the input parameter and the result set that your procedure uses). For instance, in this example the dummy table would contain the following columns: Key1 varchar(5) Lastname varchar(25) Or, if there is a table that already exists that has the exact field names/datatypes, you can use that table.


The Stored Procedure The Procedure takes input (the same as what you selected for the DECS key), and returns a result set, that includes the key and all mapped fields in the DECS Activity: CREATE PROCEDURE dbo.proc1 (@Key1 varchar(5) ) AS BEGIN select Key1, Lastname from debtest where Key1 = @Key1 END

Note If you are working with Sybase, keep in mind that Sybase is generally case sensitive, but the @var (@Key1) in the Proc must have the same name AND match case with your Sybase column and DECS mapped key. Sybase will accept a different name/case if you execute the procedure from an SQL tool, using Execute , but DECS needs the name/case to be the same or it will return the error below: 03:48:27 PM DECS: Monitor failure — Error: Procedure proc1 expects parameter @key1, which was not supplied., Connector 'sybase', Method -Call- (201): proctest Sybase Document In the Sybase Connection Document used in this example, Table was selected, not Procedure. Procedure is valid only if you are returning all values using output parameters, as is done with Oracle, for example. DECS Activity In the DECS Activity used in this example, dbo.proctable is a table created specifically with the fields required for mapping. Once the events are selected, specify the procedure to be used under the Options, as shown (proc1). After inputting the procedure name, if you press F9, it will refresh and show the input parameter that the procedure requires (Key1). At this point, DECS returns the values in the mapped fields to the Form being monitored. To use other events, create procedures appropriate to the event. Note Since the stored procedure does not return all key values, “Initialize keys” does not work with this functionality — it does not “see” the contents of a table or view. If key documents are required in Notes, create them via an agent, or by a separate DECS Activity that pulls those key values into Notes documents.


Unable to Access Data After Upgrading If after upgrading DECS, you discover you are unable to get data when you are running Virtual Fields activities, you may have to open each Virtual Fields activity document and ensure that the Domino Server chosen in the activity document is correct.

Error Messages Cannot use field [‘FIELDNAME’] as both a key and a data field Fields provided for RealTime activities must be either key fields or data fields - a field cannot be used as both in a single Virtual Fields 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 key field 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 information. Record as much information as possible about the circumstances and contact Lotus technical support.

Failure encountered in monitoring process — ERROR MESSAGE Errors that are generated by the RealTime monitors in the Domino server are logged with this prefix. The complete error text from the RealTime error is appended.

Unexpected internal failure in RealTime monitoring An internal error was encountered when attempting to access context information. Record as much information as possible about the circumstances and contact Lotus technical support.

Update of key field [‘FIELDNAME’] is not permitted Key values in a document were altered, but the Virtual Fields Activity indicated that changes to key fields should be blocked. Updates to both Notes and the back-end system were aborted.


This record has changed in the back-end database since being opened — action cancelled The Virtual Fields Activity option to check the external system for changes before writing changes to the back end was enabled, and the check indicated changes in the back end. Since the document was opened, another system or client changed the corresponding external record.

Cannot locate corresponding external record The key values in the opened document being monitored by a Virtual Fields Activity did not correspond to a record in the external system. This error can be suppressed by selecting the Virtual Fields Activity option to create the external record if it doesn’t exist — instead of the error, a new record corresponding to the current Notes document data will be created.

Failure compiling Filter Formula: FORMULA COMPILATION ERROR The filter formula provided for the Virtual Fields Activity failed compilation. The compilation error is generated with the error message. Fix or remove the filter formula to successfully run the Virtual Fields Activity.

Failure compiling Pre-Open Formula: FORMULA COMPILATION ERROR The pre-open formula provided for the Virtual Fields Activity failed compilation. The compilation error is generated with the error message. Fix or remove the pre-open formula to successfully run the Virtual Fields Activity.

Failure compiling Post-Update Formula: FORMULA COMPILATION ERROR The post-update formula provided for the Virtual Fields Activity failed compilation. The compilation error is generated with the error message. Fix or remove the post-update formula to successfully run the Virtual Fields Activity.

Failure compiling Post-Create Formula: FORMULA COMPILATION ERROR The post-create formula provided for the Virtual Fields Activity failed compilation. The compilation error is generated with the error message. Fix or remove the post-create formula to successfully run the Virtual Fields Activity.


Failure compiling Post-Delete Formula: FORMULA COMPILATION ERROR The post-delete formula provided for the Virtual Fields Activity failed compilation. The compilation error is generated with the error message. Fix or remove the post-delete formula to successfully run the Virtual Fields Activity.

Unknown OS error: libdecsext.* This is a Notes error reporting that Notes couldn’t load the DECS extension manager library. Check that you have properly installed and configured DECS. If problems persist, contact technical support.

Realtime service addin task initialization failed This indicates that the LEI addin task startup encountered an error. Check that 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 Realtime Service is unable to allocate additional resources. Check that you have properly installed and configured LEI. If problems persist, contact Lotus software technical support.

Realtime service cannot connect to external system You may not have the proper connectivity software installed that is required for accessing the external data system. Refer to the Lotus Enterprise Integrator Installation Guide for information about the native software required for connectivity to each of the LEI supported data sources.

Realtime service cannot find external table/metadata The metadata selected for this activity does not exist in the back end data source.

Realtime service cannot find external procedure/transaction The document open event captured by LEI encountered an error. The error details are logged to the Domino server log.

Realtime service error retrieving external record The document open event captured by LEI encountered an error. The error details 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. The error 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. The error 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. The error details are logged to the Administrator activity log for this activity.

Realtime service cannot locate the corresponding record in the external system The document key field values do not correspond to a record in the back end data source. The record in the external data system may have been deleted.

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 document has been opened. To allow key field changes, select the appropriate setting for the option Key Field Updates in the Document Update options section of the Activity Document.

Realtime service is unable to update document due to conflict; the external record has been modified since being opened The external data has been modified by another application since the document 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 the external data store.

Realtime service error retrieving external attachment There was a problem retrieving the attachment portion of the document from 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 in the external data store. Appendix A: Configuration and Troubleshooting 99

Realtime service data overflow accessing external record For document Open events, this indicates that data in an external field was too 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 Administrator activity log for this activity for information on which field caused the overflow.) For document updates and inserts, this message indicates that the document data overflowed a back end field. You may need to change the data type in the back end to store large amounts of data.

Realtime service encountered invalid or corrupt Notes data in the external system Information not yet available.

Realtime service error deleting external attachment There was a problem deleting the attachment portion of the document from the external data store.

Realtime service error browsing the external system There was a problem retrieving information about the names of tables in the database, or retrieving the datatype information about the columns in a particular table.

Realtime service encountered an invalid external field configuration in form Information not yet available.

Realtime service encountered a missing or invalid Data Connection Resource You get this message when you are using the Domino Designer Data Connection Resource (DCR). The Data Connection Resource that was referred to by one or more of the fields on the form is not valid, or could not be located.

Realtime service error scanning the external system. Some external records may have been ignored During a view refresh, an error occurred when retrieving document information from the external data store.

Realtime service error loading external agents/design elements An error occurred while accessing a virtual agent. 100 DECS Installation and User Guide

Realtime service error retrieving external agent/design element Information not yet available.

Realtime service error writing external agent/design element Information not yet available.

Realtime service error deleting external agent/design element Information not yet available.

This application uses a Realtime Service Activity which is currently not running. Contact your Notes administrator. During an attempt to open or delete a document, a needed running Virtual Fields Activity could not be found. Verify that the activity monitoring this database form is running. If so, fully refresh your view (SHIFT-F9) in the possibility that the external data source record has been deleted. Also check the activity log for any additional error information.


Index A

C

Access Control List (ACL) and DECS, 6 Accessibility in DECS, 3 Accessing Different External Sources, 70 ACL See Access Control List Action bar Activities view, 12 Connections view, 12 Favorites view, 15 Activities View, 9, 12 Activity add, 13 log, 13 start, 13 stop, 13 Virtual Fields, description, 2, 25 Activity Icons, 14, 31 Activity Logging in Virtual Fields and Documents activites, 62 Activity Wizard introduction, 29 Add activity, 13 Administrator DECS, 9 replacing design when upgrading, 6

Clustered Domino Server Environment and DECS, 92 Computed Subforms in Virtual Fields, 39 Conflict detection do not use with HTTP server, 28 limitations of this option, 58 Connection add, 12 Connection document creating, 19 definition, 19 fields, 21 options, 21 Connections View, 9, 12 Create Virtual Fields or Virtual Documents Activity using the Wizard, 31 Virtual Fields or Virtual Documents Activity without using the Wizard, 40 Create options in Virtual Fields and Documents activities, 53

B Building a Notes Application and using Virtual Attachments, 63

D Data sources supported, 3 Data Storage Options in Virtual Fields, 71 DECS Administrator, 9 Administrator navigator, 9 and accessibility, 3 and clustered Domino server environment, 92 and the Access Control List (ACL), 6 installing, 5 uninstalling, 7

upgrading to DECS 6, 6 DECS Administrator adding an empty, 7 menu commands, 17 replacing design when upgrading, 6 DECS Name and Address Book access, 30 DECS Virtual Fields introduction, 2 Deletion Options in Virtual Fields and Documents activities, 59 Disabling user assistant, 30 Domino/Notes consideration when installed as an NT Sevice, 91 Dynamic Queries example using Notes client and Virtual Fields, 86 in Virtual Fields activities, 83 overview of use in Virtual Field, 83

E Enable Subforms in Virtual Fields, 39, 42 Error Messages for Advanced RealTime activities, 96 Event Options in Virtual Fields and Documents activities, 52 External Data System saving data to using Virtual Fields, 70

F Favorites folder or view, 9 View, 15 Filter Formulas

103

example of using in Virtual Fields, 69 Form to monitor, 33 Form Override in Virtual Fields activities, 33, 42

G General Options, Event Options, Scheduling, and Logging for Virtual Fields or Documents, 44

H HTTP Server do not use with Conflict Detection, 28 in Virtual Fields Activities, 28

I Icon activities view, 9 activity, 14, 31 Assistant (Wizard), 10 connections view, 9 favorites view, 9 help, 10 info, 9 running, 10 Wizard, 10 Indexing in Virtual Fields, 28 key fields in Virtual Fields activities, 28 Initialize Keys in Virtual Fields, 49 Installing DECS, 5

K Key documents, 26 how they work, 27 Key field datatypes in Virtual Fields Activities, 28

L Limitations current, 6 Log

activity, 13 LotusScript Agents running unrestricted, 7

M Manual button, 23 Mapped key fields indexing in Virtual Fields activities, 28 Menu commands DECS Administrator, 17 Monitor form, 33 Monitor all forms Virtual Fields option, 42 Monitor Order and multiple Virtual Fields activities, 26 Monitor Orders Option using in Virtual Fields, 71 Multi-Value Data in Virtual Fields, 50

N Name and Address Book access, 30 of DECS server and access, 5 Navigator, 9 Notes Clients example of dynamic queries using Virtual Fields activities, 86 NOTRES.INI variables, 89 NT Service and Domino/Notes, 91

O OLE DB Connector mapping key fields in Virtual Fields activities, 36, 43 OLEDB issues when using stored procedures, 93 OLEDB Connection Document select Table when using stored procedures, 73, 94 Open options in Virtual Fields and Documents activities, 55 Options connection document, 21


examples of using in a Virtual Fields activity document, 69 Scheduling in Virtual Fields and Documents activities, 61 Oracle Stored Procedure example used with Virtual Fields, 79 input and named parameters, 79 output parameters, 80

P Password, 21 Performance, 28, 29 Privileges lack of: results in not seeing data, 27 Process Virtual Fields or Documents activity, 40, 44

R RealTime activity See Virtual Fields activity Replication id and Virtual Fields and Documents, 32, 41

S Scheduling in Virtual Fields and Documents activities, 61 Selection Type, 21 Start activity, 13 Stop activity, 13 Stored procedure, 23 Sybase/SQL example, 73 using DB2 stored procedures in Virtual Fields Activities, 77 using Oracle stored procedures in Virtual Fields Activities, 79 Stored Procedure Definitions examples used in Virtual Fields, 75 Stored procedures errors when attempting to use Sybase or OLEDB stored procedures with Virtual Fields, 93

testing DB2 in Virtual Fields activities, 77 testing SQL in Virtual Fields activities, 75 use table in Sybase/SQL, 73 using Sybase and SQL stored procedures in Virtual Fields, 73 Stub documents See key documents Subforms enable, 39 Supported Data Sources, 3 Sybase issues when using stored procedures, 93 Sybase Connection Document select Table when using stored procedures, 73, 94

T Troubleshooting Inability to get data after an upgrade, 96

U UNID as key field, 36 Uninstalling DECS, 7 Update options in Virtual Fields and Documents activities, 57 Updating need for write permission, 37 Upgrading to DECS 6, 6 troubleshooting inability to get data, 96 User assistant disabling, 30 turning on, 29

V View Activities, 9, 12 by Domino Application, 13 Connections, 9, 12 Favorites, 9, 15 Views, 9 Virtual Documents

Activity Logging, 62 building a Notes Application that uses Virtual Attachments, 63 delete options, 59 document create options, 53 document open options, 55 Event Options, 52 General Options, Event Options, Scheduling, and Logging, 44 update options, 57 Virtual Fields Activity Logging, 62 building a Notes Application that uses Virtual Attachments, 63 building views in, 71 delete options, 59 document create options, 53 document open options, 55 dynamic queries, 83 dynamic queries Notes clients, examples, 86 dynamic queries from Web clients, examples, 84 dynamic queries, examples, 83 Event Options, 52 general options, 45 General Options, Event Options, Scheduling, and Logging, 44 initialize keys, 49 multi-value data, 50 update options, 57 Virtual Fields Activities accessing different external sources, 70 and clustered Domino server environment, 92 and monitor order, 26 data storage options, 71 description, 2, 25 examples of using the activity options, 69 filter formula, example of using, 69 saving data to external system, 70 storing a static copy of external data, 71 testing stored procedures in SQL, 75 using an Oracle Stored Procedure, 79 using Sybase and SQL stored procedures, 73 using the monitor orders option, 71

W Web sites DECS, vi LEI, vi PTFs, vi Wizard turning off, 30 turning on, 29 using to create a connection document, 19 using to create a Virtual Fields or Documents activity, 31 Write permission needed when updating, 37

Index 105