Creating the Activity

Activities define what happens when the connection is made to the external data source. Activities can be created to retrieve information from a data source and populate a field in a Domino database or to take the data in a Domino database field and update the back-end data source. In other words, an activity defines the relationship between the Domino application and the data source.

So, you're now ready to create an activity. When Create Activity is chosen from the Navigator pane, the activity form appears, as shown in Figure 22.5. The dialog box that pops up appears every time you create a new activity unless you turn off the User Assistant from the Navigator pane.

Figure 22.5. The Creating a Virtual Fields Activity dialog box appears as long as the User Assistant is turned on.

NOTE

To turn the User Assistant off, click the Disable Assistant hotspot label. If you want to turn the User Assistant back on, simply click the Enable Assistant hotspot label again.

After you close the dialog box, another one pops up with a list of Notes databases from which to choose. Select the appsCust6.nsf database as shown in Figure 22.6.

Figure 22.6. The Select Domino Database dialog box provides a list of available databases to choose from.

After you select the Customer database, you get another dialog box that prompts you for the form, or metadata, that you want to use from the Customer database. Select the CustKey form, as shown in Figure 22.7.

Figure 22.7. The Notes Selection dialog box is where you select the form to use in mapping the data.

When you select the form, you get another dialog box that prompts you for the ODBC connection that you'll use to connect to the external data source. Select the CUSTOMERR6 data source (or whatever you have named your ODBC connection), as shown in Figure 22.8.

Figure 22.8. The Select Connection dialog box lists all the connections that have been created in the DECS Administration database.

The Custdata table is selected as it was defined in the Connection document, so now you're ready to begin mapping fields. From the Key and Data Field Mapping section of the form, select the appropriate fields as indicated in Figure 22.9.

Figure 22.9. The Key and Data Field Mapping section shows the fields in each of the data sources and enables you to define how they're mapped.

To map the fields, you simply check the field names that you want to use as the key fields and the fields that you want to be able to access.

Next , you need to make a few key decisions for this activity. The first decision is which events you want to invoke for the application. The available events are listed in Table 22.2. You're going to invoke all the events because you want to be able to both access the external data in the documents and add new and modified data back to the external data source as data is added and changed in Notes.

Table 22.2. Events

Next, you have to set up any options that you need to use. By expanding the Options section, as shown in Figure 22.10, you can set the general options and then determine which options to choose for each of the events that you've invoked. You will not change any of the defaults for the available options.

Figure 22.10. The expanded Options section of the Activity document provides a place to define additional processing that should take place when an event is invoked.

General Options

The general options apply to all the events that have been enabled for the activity. These options are shown in Figure 22.11.

Figure 22.11. The general options for an activity are applied to all events.

The first option is Monitor Order. This is useful if there are multiple activities running against the same form that have to occur in a specific order to be successful. That is, if you have an activity called B that needs data that is the result of another activity called A, you set Monitor Order to 1 for activity A and Monitor Order to 2 for activity B.

The second option is Max. Connections. This determines how many concurrent connections can be made to this data source at one time. A connection transaction occurs very quickly, so you should not have to set this to more than 2 or 3. Many ODBC connections accept only one connection at a time, and with a setting higher than 1, additional users connecting could encounter an error message if a connection is already established.

The third option is Form Override. You specified the form you'll use earlier in the Notes Application section of the activity document. By choosing to override the form, you're saying that for all events indicated here, you want to monitor all documents in the database that have the same key field data. For this application, you don't use this option, but instead have two separate activities: one for the customer data that monitors all events and one for the customer calls that monitor only the Open event.

The fourth option is Filter Formula, which provides the ability to set a formula to determine a subset of documents in the database to be monitored with this activity. This is useful if there are multiple external databases that should be accessed based on things such as region, business segment, and so on.

The Data Integrity options define what to do in the case of information entered into the application that doesn't conform to the requirements for the external data source, such as field lengths. Allow Precision Loss is the default.

The Trim Trailing Spaces options define how trailing spaces in the data in the external data source should be handled when it comes into Notes.

The Data Storage options determine whether the data that's retrieved from the external data source is actually saved with the document. By default, the data isn't saved. The other options are to store all the fields in documents or to select specific fields. So, when do you want to save the data? Save it if you have remote users accessing the application locally, if the application is on multiple servers and not all servers have DECS running, or if you want to create views that include any of the Virtual Fields. The Error Logging option determines where DECS errors are logged. The choices are to log to a document or to the Notes Log and the Activity log.

The Caching option should be used when there are a lot of changes written back to the external data source.

Document Creation Options

The document creation options are available only when creating a new document that is written back to the external data source. These options are displayed in Figure 22.12.

Figure 22.12. The document creation options in the activity document provide a means for running a stored procedure when the event occurs.

The Pre-Create Formula option provides an opportunity to have a formula run against the document before it's saved in the external data source.

The Stored Procedure option provides an opportunity to run a program that can manipulate the data for the external data source as the data is saved.

Document Open Options

The document open options are available only when opening an existing document, and are displayed in Figure 22.13.

Figure 22.13. The document open options of the activity document include additional options.

The Pre-Open Formula option provides an opportunity to execute a formula against the document before the external data is retrieved, thus allowing key updates to occur based upon information in the document.

The Post-Open Formula option provides an opportunity to manipulate the data being read into the document from the external data source. This is particularly helpful when you want to parse the data coming in from a specific field to place it in multiple fields in the document.

The Stored Procedure option provides an opportunity to execute a procedure that determines what data is retrieved based on the query.

The Missing External Records option provides an opportunity to have a new record written in the external data source if the key isn't found when opening an existing document.

Document Update Options

The document update options are available only when editing an existing document that's written back to the external data source. The document update options are displayed in Figure 22.14.

Figure 22.14. Document updates can be further defined in the Options section of the activity document.

The Pre-Update Formula option runs a formula as specified against the data prior to updating it in the external data source.

The Stored Procedure option provides an opportunity to run a procedure that can manipulate the data for the external data source as the data is saved.

The Conflict Detection option checks to see whether the matching record in the external data source has changed since it was opened. If it has, the update fails.

The Field Level Updates option updates fields in the external data source only if the fields have been edited in the Notes document.

The Key Field Updates option determines how changes to key fields made in the Notes document are handled in the external data source. The first option is to block all key field changes, which means that a key field cannot be changed in Notes or the external data source. The second option is to delete the existing record in the external data source and then insert a new record with the new values. The last option is to ignore the changes in Notes and do nothing to the record in the external data source.

Document Deletion Options

The document deletion options are available only when deleting an existing document in the external data source; they're displayed in Figure 22.15.

Figure 22.15. The document deletion options for the activity document only provide additional options for running a stored procedure or formula.

The Pre-Delete Formula option provides an opportunity to specify a formula that is to run prior to deleting the document.

The Stored Procedure option runs a named procedure on the external data source when deleting the record.

Creating an Activity Without the User Assistant

In your application, you can retrieve the customer data in the customer documents and you can also create documents to log calls from customers. To create customer calls that also display the customer information that's stored in the external data source, you must have another activity to support the open activity for the custcall form.

So, create this activity without the aid of the User Assistant. First, turn off the User Assistant by clicking on the "Disable Assistant" hotspot label in the Navigator pane, as shown in Figure 22.16.

Figure 22.16. The User Assistant is turned off when the hotspot in the Navigator says Disable Assistant.

Next, create a new activity and name it CallTrack. Then click the button next to the Notes Application label. This brings up the dialog box to select the database to monitor. Choose the appsCust6.NSF file and click OK. This then invokes the dialog box to select the form to monitor. Choose the Customer Call form and click OK. Your selections should look like the selections in Figure 22.17.

Figure 22.17. The completed Customer Call Activity document shows both data sources selected.

Next, choose the button next to the Lotus Connection. This brings up the dialog box to select the ODBC connection. Choose the CUSTOMERR6 connection (or whatever you've named the connection), and choose OK. This brings up the dialog box to select the table. Choose the CustMain table. Check Figure 22.17 to be sure that you choose the appropriate options.

Next click the button next to Mapping and map the fields as shown in Figure 22.17.

Lastly, choose just the Open event to monitor. That's it ”you're now ready to set up and test DECS in the application.