Putting Your Agent to Work

As always, the Design pane or Programmer's pane occupies the right portion of the Design window. Agents can perform simple actions, formulas, LotusScript, imported Java, or Java. Many common tasks can be accomplished using simple actions; simple actions can be combined with each other and with @Functions. The Formula language can handle more sophisticated agents. However, neither simple actions nor formulas can be combined with LotusScript or Java. LotusScript and Java are particularly suited to agents because they can iteratively process documents. Neither simple actions nor the Formula language can do that because they are limited to a single pass through the documents. Java agents provide portability of agents to Web browsers.

Defining Simple Actions in Agents

Simple actions are options that you can choose to execute a set of commands automatically. Click the Add Actions button to view the Simple Actions commands. The name of the action defines the task that is executed when the agent is run. The following is a list of the available simple actions, as shown in Figure 11.13:

• Copy to Database
• Copy to Folder
• Delete from Database
• Mark Document Read
• Mark Document Unread
• Modify Field
• Modify Fields by Form
• Move to Folder
• Remove from Folder
• Reply to Sender
• Run Agent
• Send Document
• Send Mail Message
• Send Newsletter Summary
• @Function Formula

Figure 11.13. The simple actions choices.

Simple actions can be added together in the same manner as search criteria. These actions are then performed in sequence, with the following exception: the Delete from Database action is always executed last, regardless of its position in the Simple Action window. To use a simple action in an agent, click the Run Simple Action radio button. Click the Add Action button to add an action. After the action is programmed and saved, you can add additional actions to the agent by clicking the Add Action button again. You can edit actions by double-clicking the text with the gray background in the Design pane that symbolizes the action. Although simple actions are limited, they can be useful. They are particularly useful for end users because of the ease with which they can be programmed.

In a mail-in database, an agent using the Reply to Sender simple action can send a confirmation of receipt to the person emailing a document to the database. Creating an action such as this is easy because it requires no knowledge of the Formula language or of LotusScript. Simple action agents can also be used to chain together more than one agent by using the Run Agent action. To be able to run, this agent must already exist in the database.

An example of a limitation of simple actions is the Modify Field action. This allows you to replace or append a field's value. You cannot store the value of another field in the field to be modified with this action. To do that, you must either choose the Run @Function simple action or use an agent based on the Formula language or LotusScript.

Using Formulas in Agents

Formula-based agents, or agents based on the Domino Formula language, are significantly more powerful than simple action agents. Formulas for agents can be added to a simple action by clicking the Add Action button and selecting @Function Formula in the Action drop-down selection field. Formula-based agents have a special list box that appears in the lower-right corner of the Design pane. This is illustrated in Figure 11.14. The list box has the following three selections:

• Modify Documents (the default)
• Create New Documents
• Select Documents in View

Figure 11.14. A formula-based agent can use many actions.

Most often, you will write agents that modify documents. The agent in Listing 11.1 is an example of one that modifies documents. You might occasionally create an agent that creates a new document and perhaps archives the original. Search agents can be used to select documents in view and will place a check mark in the view selection margin next to the documents that meet the selection criteria.

Creating a formula-based agent requires a SELECT statement. If one is not present, Domino appends SE LECT @All to the end of the formula. If you want to change the SELECT statement to restrict documents, the statement must be placed at the beginning of the formula or it will not function. The SELECT statement can be used to further refine the selection criteria or the documents that the agent selects and works on. If an agent includes a SELECT statement that specifies a condition instead of selecting all documents, you should test the agent using Select Documents in View to ensure that you are selecting the appropriate documents before choosing to modify documents.

Formulas for agents can easily manipulate field values using the FIELD keyword or the @SetField() function. Using one of these two options allows the value of the field to be set to that of another field, a combination of fields and text, and so on. You can also create and delete fields in documents. None of this is possible with a simple action.

You will find that through the course of developing an application, you might need to change field names . Be warned : If documents already exist in the database, the new field name will not be updated in the existing documents. Listing 11.1 displays the code for an agent to make these changes.

Listing 11.1 Moving Data from an Old Field to a New Field in an Existing Document

SELECT Form = "Name of Form";
FIELD NewField := OldField;
FIELD OldField := @DeleteField;

Another agent that is frequently used by developers is one to recalculate all the fields in existing documents based on design changes made to the forms. This can be accomplished through a formula agent, as shown in Listing 11.2.

Listing 11.2 Recalculating Fields in Documents

@Command([ToolsRefreshAllDocs])

TIP

Setting a flag when an agent processes a certain document is often useful. This flag can be used to limit further actions by the agent or can be used simply for informational purposes.

 

The following code fragment illustrates a way to set a flag in a document:

REM {Mark document as run and set a flag}; 
REM;
FIELD ChkResponse := @Now;
FIELD ReviewersNotified := "No";
FIELD CheckFlag := "On";
...

These fields did not originally exist in the document but were added using the Formula language via the agent. The value of fields set by the agent can be checked in subsequent runs. For example, in the preceding code fragment is a flag field called ReviewersNotified. If certain conditions were met, the reviewers would be notified by email and the value of this field would be set to Yes. When the agent executes in the future, the SELECT statement could be used to prevent the agent from executing on this document. Otherwise, reviewers would be notified on all subsequent runs of the agent. Such a selection statement might look like the following:

SELECT ((FORM = "ECR":"ECS") & ECRStatus = "Released for Review" & ReviewersNotified !=

"Yes") @ISResponseDoc