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

Transcription

1

2 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 Lotus Development Corporation Copyright 2002 All Rights Reserved. IBM Corporation Lotus Software, IBM Software Group One Rogers Street Cambridge, MA 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.

3 Contents Preface... v Related Documentation... 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... Security... 2 Installing DECS... DECS Installation... After Upgrading to DECS Replace Administrator Design... DECS Virtual Fields Activities in a Clustered Domino Server Environment. 6 Installation Considerations... 6 DECS and Access Control List (ACL) Levels.. 6 Running Restricted LotusScript Agents... 7 Uninstalling DECS... 3 DECS Administrator... 9 The DECS Administrator... 9 DECS Administrator Navigator... 9 Connections View... Activities View... Favorites View... Main Menu Commands Defining Lotus Connections... Defining Lotus Connections... Connection Document Fields... Using the Manual Button... Completed Connection Document... 5 Virtual Fields Activities... Introduction to Virtual Fields Activities... 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... 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... Step 4 Select the Lotus Connection for the Data Source... Step 5 Map Data Field(s)... 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 iii

4 Step 11 Save and Close the Document. Step 12 Initialize Keys... Step 13 Process the Virtual Fields Activity... Creating an Activity without the User Assistant... Step 1 Click the Add Activity Icon... Step 2 Enter a Name for the Activity.. Step 3 Select the Domino Application and the Form to Monitor... Step 4 Select the Lotus Connection for the Data Source... Step 5 Enable Subforms... Step 6 Mapping... Step 7 Select Event(s) to Monitor... Step 8 Select Options and Initialize Keys Step 9 Select Scheduling Options... 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. Building a Domino Application for a Virtual Fields Activity... Example Application Example of the Application Design View... Virtual Fields Activity Example... Running the Virtual Fields Activity... 7 Using Virtual Fields Activity Options... Using the Options in a Virtual Fields Activity Document... Using Filter Formulas... Saving Data to an External Data System.. Accessing Different External Sources using the Same Notes Application... Using Data Storage Options... 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.. Testing the Stored Procedures in Sybase/SQL Using a DB2 Stored Procedure... Using an Oracle Stored Procedure... Input Values and Named Parameters... Output Parameters... 8 Virtual Fields and Dynamic Queries... Overview of Virtual Fields Dynamic Queries Virtual Fields Dynamic Queries from Web Clients... Overview of Steps... Example of Virtual Fields Dynamic Queries from Notes Clients... Appendix A Configuration and Troubleshooting... Index iv DECS Installation and User Guide

5 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 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 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 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 Current information about DECS can also be found at 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

6 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: Note Domino-related product updates for iseries can be found at following Web site: u.htm Technical Support To contact Customer Support with suggestions or questions regarding your Lotus Connector or DECS application, call vi DECS Installation and User Guide

7 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 Chapter 1 Introduction Chapter 2 Installing DECS Chapter 3 DECS Administrator Chapter 4 Defining Lotus Connections Chapter 5 Virtual Fields Activities Chapter 6 Building a Domino Application Chapter 7 Using Virtual Fields Activity Options Description 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. This chapter provides information about installing and configuring DECS. This chapter provides information about the DECS navigator, views, icons, and menu commands. This chapter provides information and instructions for creating Connection Documents. This chapter provides an overview of Virtual Fields activities, information regarding preparation of external system fields, and instructions for creating Virtual Fields Activities. This chapter provides information for creating a Domino application for use with a Virtual Fields Activity. This chapter provides examples using Virtual Fields options to refine the results of Virtual Fields Activities. continued 1

8 Section Chapter 8 Virtual Fields and Dynamic Queries Appendix A Configuration and Troubleshooting Description This chapter provides information on how to use Virtual Fields for on-demand, dynamic queries of external data. 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 or Domino 6 server, obtaining access to supported external source data. 2 DECS Installation and User Guide

9 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: 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 Chapter 1: Introduction 3

10 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 <Ctrl> 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 <Alt> 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

11 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

12 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. 6 DECS Installation and User Guide

13 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

14

15 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

16 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. 10 DECS Installation and User Guide

17 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

18 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: 12 DECS Installation and User Guide

19 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. Chapter 3: DECS Administrator 13

20 Activity Icons The following table describes the information shown in the Activities view of the DECS Administrator. Column Domino Application Events Activity External Source Status Name Description and Icon Shows the name of the Notes NSF and the specific form being monitored. 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. Indicates the activity is a Virtual Fields activity. Shows the type of external data source, the database and table name or metadata. 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. The user-specified name of the Activity. 14 DECS Installation and User Guide

21 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. Chapter 3: DECS Administrator 15

22 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. 16 DECS Installation and User Guide

23 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 Other... Description 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 Reset Activity Set Autostart Remove from Folder Description Restarts the currently selected activity. 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 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 3: DECS Administrator 17

24

25 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

26 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. 20 DECS Installation and User Guide

27 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 Server/Provider/Oracle Version/SQL Server Note This field is not available for all Connection documents. Database/Engine/Directory Path/Data Source/Host String Provider String Authentication Service User Name Password Password Encryption Key Icon Description 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. 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. Enter the User Name required to access the selected data source specified above. Enter the password associated with the User Name specified above. 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

28 Connectivity Field Selection Type: Description 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. 22 DECS Installation and User Guide

29 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 Selection Field Owner (Not available in File connection documents) Name Column(s)/Parameters/File Attributes Comments Description 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. This option allows you to select from tables by owner name. The default value is <Any>, 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. 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. 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. 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

30 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. 24 DECS Installation and User Guide

31 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 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

32 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). 26 DECS Installation and User Guide

33 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

34 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

35 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. Chapter 5: Virtual Fields Activities 29

36 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. 30 DECS Installation and User Guide

37 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

38 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 (<overflow...>) 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. 32 DECS Installation and User Guide

39 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. Chapter 5: Virtual Fields Activities 33

40 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 (<overflow...>) and a box appears under the list, which you use to type in the exact name of the table you want to use. 34 DECS Installation and User Guide

41 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. Chapter 5: Virtual Fields Activities 35

42 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. 36 DECS Installation and User Guide

43 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. Chapter 5: Virtual Fields Activities 37

44 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. 38 DECS Installation and User Guide

45 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. Chapter 5: Virtual Fields Activities 39

46 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. 40 DECS Installation and User Guide

47 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 (<overflow...>) 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

48 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 (<overflow...>) 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. 42 DECS Installation and User Guide

49 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. Chapter 5: Virtual Fields Activities 43

50 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 44 DECS Installation and User Guide

51 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. Chapter 5: Virtual Fields Activities 45

52 General Options Monitor Order Max. Connections Form Override Description 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: 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. 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 46 DECS Installation and User Guide

53 General Options Filter Formula Data Integrity Description 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. 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 Chapter 5: Virtual Fields Activities 47

54 General Options Trim Trailing Spaces New Line Delimiter for Connection Data Storage Description 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. Select the option you want to use to convert the Notes new-line delimiter to a new-line delimiter in another system. 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 48 DECS Installation and User Guide

55 General Options Saved Fields Description 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. Chapter 5: Virtual Fields Activities 49

56 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 Options Multivalue Data Description 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 50 DECS Installation and User Guide

57 Multi-Value Data Options Subkey Fields Sorting Sorting fields Text order Direction Character set Description 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. 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 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. 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. 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. 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

58 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

59 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. Chapter 5: Virtual Fields Activities 53

60 Create Options Pre-Create Formula Stored Procedure Stored Procedure Output Description 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. 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. 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 54 DECS Installation and User Guide

61 Create Options Stored Procedure Output Mapping Description 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 Pre-open Formula (Virtual Fields only) Post-Open Formula Description 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. 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 = Al ; Albert ;FIRSTNAME); Note You should not use Post-Open Formulas when using conflict detection. continued Chapter 5: Virtual Fields Activities 55

62 Open Options Stored Procedure Missing External Records (Virtual Fields only) Stored Procedure Output Mapping Description 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. 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. 56 DECS Installation and User Guide

63 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 Pre-Update Formula Stored Procedure Description When a Notes document is updated, this option executes a Notes formula statement before the data is saved in the external database. 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 Chapter 5: Virtual Fields Activities 57

64 Update Options Description Stored Enable Procedure Output This option is available only if a Procedure stored procedure has been specified in the Stored Procedure Output 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 Check External Data for Changes This option ensures that the Detection 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 Key Field Updates 58 DECS Installation and User Guide 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. 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

65 Update Options Stored Procedure Output Mapping Description Document Delete Options 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. When monitoring Document Deletion Events, several options are available depending on the choices you make. A description of the options follows the illustration. Chapter 5: Virtual Fields Activities 59

66 Deletion Options Pre-Delete Formula Stored Procedure Stored Procedure Output Mapping Description 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 containing information about a deleted document: FIELD LASTNAME:=LASTNAME; FIELD 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. 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. 60 DECS Installation and User Guide

67 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 Scheduling Option Description 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. Chapter 5: Virtual Fields Activities 61

68 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. 62 DECS Installation and User Guide

69 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

70 Example Application Shown below is an application that monitors employee information in an external data source. 64 DECS Installation and User Guide

71 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

72 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. 66 DECS Installation and User Guide

73 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 - <form_name> 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

74

75 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 Filter Formulas Using Data Storage Options Using the Monitor Orders Option Using Stored Procedures in Sybase/SQL Using a DB2 Stored Procedure 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 Filter Formulas Using Data Storage Options Using the Monitor Orders Option Using Stored Procedures in Sybase/SQL Using a DB2 Stored Procedure 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

76 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. 70 DECS Installation and User Guide

77 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 Form EMPLOYEE Table DEPARTMENT Table (access with monitor order 2) LOCATION Table (access with monitor order 3) EmpID EmployeeID EmpName EmployeeName DepartmentNo (may be hidden) DeptNo DeptNo Department DeptName DepartmentLoc (may be hidden) DeptLoc LocCode Location LocName Chapter 7: Using Virtual Fields Activity Options 71

78 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 EmpID as the key DepartmentNo Employee Table EmployeeID as the key DeptNo 3. Create a second Virtual Fields activity based on the Employee Information Form and the Department Table. Select the following fields: Notes DepartmentNo as the key Department Department Table Deptno as the key 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. 72 DECS Installation and User Guide

79 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 DepartmentLoc as the key Location Location Table LocCode as the key 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. Chapter 7: Using Virtual Fields Activity Options 73

80 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. 74 DECS Installation and User Guide

81 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 varchar(20) ) as INSERT INTO addrbook Chapter 7: Using Virtual Fields Activity Options 75

82 (FirstName,LastName, MailDomain, MailServer, MailAddress, create procedure varchar(20) ) as select FirstName,LastName, MailDomain, MailServer, MailAddress, CompanyName,State from addrbook WHERE FirstName and LastName create procedure varchar(20) ) as UPDATE addrbook SET MailDomain=@MailDomain, MailServer=@MailServer, MailAddress=@MailAddress, CompanyName=@CompanyName, State=@State 76 DECS Installation and User Guide

83 WHERE and create procedure 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. Chapter 7: Using Virtual Fields Activity Options 77

84 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, 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; IN ITEMID int, IN QTY int, OUT SONUM bigint) 78 DECS Installation and User Guide

85 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

86 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

87 WHERE t.number1 = number1_request; END; END; Chapter 7: Using Virtual Fields Activity Options 81

88

89 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

90 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. 84 DECS Installation and User Guide

91 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

92 Example of Virtual Fields Dynamic Queries from Notes Clients 86 DECS Installation and User Guide 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.

93 @Command([FileSave]); Keys ; 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

94 88 DECS Installation and User Guide