Portlet Factory, Version 6.1.2
Invocation of Domino agents
The Domino View & Form builder can invoke a Domino agent in multiple ways.
Most Domino developers are familiar with the concept of a Web Query Save agent. Such an agent is referenced in a form design and runs automatically when a document edit or create event occurs by HTTP. IBM® WebSphere Portlet Factory connects to Domino by the DIIOP protocol. Therefore, the referenced Web Query Save agent does not run. Instead, the Domino View & Form builder offers greater flexibility by allowing different agents to be invoked for a document edit and a document create event. When WebSphere Portlet Factory invokes an agent, it waits until the agent completes its tasks before it moves to the next operation.
When an agent should be run with some other event, that agent can be invoked using the linked Java object helper class included with the Domino View & Form builder. This linked Java object is present in the model whenever a Domino View & Form builder call is present. It might be useful in certain circumstances to process several documents and run an agent against all of those documents rather than run an agent against each document as it is being saved. Invocation of Domino agents involve the following considerations:
- Ways to invoke a Domino agent
- Criteria for running certain agents
- Passing the document ID number
- Signing an agent
- Reading and writing items with multiple values
Ways to invoke a Domino agent
The Domino View & Form builder can invoke a Domino agent in the following ways:
- Domino View & Form Builder user interface, with a document edit or a document create operation
The Document Edit and Document Create input sets provide an input that allows you to specify the name of a Domino agent to run with an edit or create operation.
- Linked Java object helper method
The helper linked Java object used by this builder includes a runAgent() method that you can call to invoke an agent. The arguments to the method specify the name of the agent to run and the name of the Notes document to operate on.
The UNID parameter is optional and is only needed if the specified agent uses the getParameterDocID method to access a particular document.
Criteria for running certain agents
An agent to be invoked must be designed according to the following specifications:
- The agent must be triggered by On Event using Action menu selection or Agent list selection.
- Target documents must be None.
- The agent must be LotusScript or Java. Formula language agents do not work.
Passing the document ID number
The NoteID of the document is passed by WebSphere Portlet Factory automatically. Consequently, the runAgent() method of the helper class can be invoked with only the first argument. The assumption is that, if the second argument is omitted, the NoteID of the current document is used instead. As a result, using the single argument version of this method runs the agent on the current document.
Using both arguments on the runAgent() method means that the agent needs to run against a different document: the one whose NoteID matches the second argument.
In the agent, use the ParameterDocID property to retrieve the NoteID. This property is accessed differently depending upon whether the agent is written in LotusScript or Java. This property contains the value of the NoteID passed by the linked Java object.
- LotusScript
- NotesAgent.ParameterDocID
- Java
- NotesAgent.getParameterDocID()
Having the NoteID is not enough. The agent must use a method to get the document. Keep in mind that the agent passes NoteID and note document UNID. Therefore, get the document using the GetDocumentByID() method and not GetDocumentByUNID(). These methods differ slightly between LotusScript and Java.
- LotusScript
- NotesDatabase.GetDocumentByID(NoteID)
- Java
- Database.getDocumentByID(String noteid)
It is important to use the correct methods because NoteIDs and UNIDs do not work the same way.
Signing an agent
When trying to run agents by DIIOP, consider a security element: agent signing. For an agent to run on a Domino server, it must be signed by a user with authority to run that type of agent. The agent signer must also have sufficient rights to the database to perform the tasks contained in the agent. For example, if the agent is signed by a user with only Reader access to the database and the agent is designed to make changes to a document, the agent does not run properly because the agent signer does not have permission to make document changes.
If the agent is invoked by means of the DIIOP protocol, the Run as Web User option in the agent security settings does not mean anything. This option, therefore, has no bearing on whether the agent runs when it is invoked from WebSphere Portlet Factory.
An agent can be signed by Domino Designer or Domino Administrator by first switching to the Notes ID of the user which is intended to provide the signature. In Domino Designer, open and resave the agent. In Domino Administrator, find the database in the Files tool, right-click it, and choose Sign.
Reading and writing items with multiple values
Many Notes forms have fields that can hold multiple values, but in fact are used just for a single value. When a document item containing multiple values is read (using the readDocument method of the DominoHelper class), it is put into a single String with values separated by a separator character. The default separator is | (vertical bar). If a document is written (using the updateDocument or createDocument method of the helper) and if item text contains the separator, the field value is parsed into multiple entries with multiple values written to the document item in Notes.
You can change the separator character from the default, using the following helper method:
setItemValueSeparator(String separator)The specified separator is then used for all read and write operations for that helper instance.
Parent topic: Domino View & Form builder
Library | Support |