Creating a Complex Agent

This section demonstrates a simple piece of code that enables users to mail a document to a database. This agent includes an attached graphic with the document that is mailed. The document will be mailed to a central repository for graphics elements within a given company that can later be used in other Domino applications. This example provides you with a practical application for learning how to use agents for mailing purposes as well as for storing attachments.

This database consists of a form named NewGraphicNG that contains the information we are interested in displaying from the mail message that is received. For the database to receive mail, a mail-in database record must be created. When the database receives mail, the form is the Mail Memo form. This must be changed to the form name NewGraphicNG, and the unnecessary fields must be stripped from the document. The name of the person mailing the document must be appended to the subject of the memo and stored in the Comment field. A message must be sent on receipt of the mail to the graphics database manager (GMan) because he must approve the graphic before it can be made available to the users of the database for inclusion into any of the company's applications. A confirmation message to the sender of the graphic indicating that the graphic was received and is under consideration also needs to be sent. To illustrate several techniques, the architecture of this agent is a bit more complex than is probably necessary.

First, a Reply to Sender simple action agent was created with a New Mail trigger. Figure 11.15 shows the Reply to Sender action being defined. The reply message is simple and straightforward. Because this is a simple action, it executes with the New Mail trigger.

Figure 11.15. The Confirmation agent during design displays the Add Action dialog box for creating the Reply to Sender simple action.

Next, a formula-based agent to convert the form name was created to modify fields and delete unnecessary fields. This is the Convert Mail Memo agent, which has a trigger of All New or Modified Documents. This is the formula, as shown in Listing 11.3.

Listing 11.3 Formula Agent for the Submission of a New Graphics File

REM {Make sure this runs only on Memo forms. This effectively limits the execution of the agent}; REM {because the form is changed from Memo to NG} ; REM; SELECT Form = "Memo" ; REM {Change Form to Mail Convert form} ; FIELD Form := "NG" ; REM {Initialize fields} ; FIELD cComment := Subject + ", submitted by " +@Name([CN];From) ; FIELD NGReaders :="GMan" ; REM "Delete fields" ; FIELD Subject := @DeleteField ; FIELD From := @DeleteField; FIELD Categories := @DeleteField ; FIELD CopyTo := @DeleteField; FIELD DefaultMailSaveOptions := @DeleteField; FIELD DeliveredDate := @DeleteField; FIELD Encrypt := @DeleteField; FIELD LayoutField := @DeleteField; FIELD Logo := @DeleteField; FIELD MailSaveOptions := @DeleteField; FIELD PostedDate := @DeleteField; FIELD PRINCIPAL := @DeleteField; FIELD RouteServers := @DeleteField; FIELD RouteTimes := @DeleteField; FIELD SECURE-MAIL := @DeleteField; FIELD SenderTag := @DeleteField; FIELD SendTo := @DeleteField; FIELD Sign := @DeleteField; REM {The AuthorList field gets added by Domino and will allow access because it is a read/ edit } ; REM {access field. Delete it to prevent accidental access to the documents.} ; FIELD AuthorList := @DeleteField; REM { A mail message should now go to the database administrator notifying him/her}; REM {that the graphic has been submitted for approval}; @MailSend(NGReaders;"";"";"New Graphic Submission";"";"The attached document has been submitted for review";[IncludeDocLink]);

Notice that the agent automatically sends a message with a doclink to the database administrator to review and approve the graphic. Email confirmation could have been sent to the sender directly from this formula agent, but it was performed this way to illustrate how it can be done with a simple action agent. Another possible technique is to combine the Reply to Sender simple action with the Run Agent simple action. This is illustrated in Figure 11.16. Because this is a formula-based agent, you cannot use the New Mail trigger; instead, you must use the All New or Modified Documents trigger.

Figure 11.16. The Process Mail agent replies to the sender and runs the Convert Mail Memo agent.

One more problem must be solved . When the NGReaders field is created in a document, even though it is a Reader Names field on the NewGraphicNG form, it ends up being a text field until the document is refreshed. It is too bad that the field type cannot be enforced. Unfortunately, there is no easy way to refresh a document via an automatic agent. The only technique available with traditional coding methods is to use a Run Once agent with @Command([ToolsRefreshAllDocs]) or @Command([ToolsRefreshSelectedDocs]) . Run Once agents are manual agents, and because this @Command relates to the UI, it will not execute when called from another agent. Therefore, the agent must be run by an administrator after the database is opened.

Next, let's see how this same agent can be constructed using LotusScript.