ShowTable of Contents
Many customers have asked how to run an agent on selected documents in the iNotes inbox. They may want to archive the documents, copy them to another database, or just update them in some way. This article shows you an example of how to do it.
In this example, we add a button to the action bar menu in the Mail Inbox view. We connect a function to the button that gets the UNIDs of the selected documents, and sends those UNIDs to an agent. When the agent finishes, the inbox is refreshed. In the example, our agent simply adds the text "UPDATED: " to the subject of each selected document and then saves the document.
Create an Extension Forms File
If you don't already have one, create an Extension Forms File. This is where all the customizations in this example will go. Information on creating the Extension Forms File can be found in the Domino and Notes information center topic
Customizing the look of Lotus iNotes.
Add a button to the Inbox view
To add a button to the action bar in the Inbox view, we'll edit the
Custom_JS_Lite subform in the Extension Forms File. First, we'll remove the comment tags around the inclusion of the subform
API_ActionsHelper_Subform_Lite:
<NotesComment>
// Expose this comment block to include actions helper routines for Lite mode
<InsertNotesSubForm Name=API_ActionsHelper_Subform_Lite>
</NotesComment>
Then, we'll add code in the
Custom_Scene_Actions_Lite function to add a button.
// Only add the menu item if we're in the mail view
if (-1 == s_MenuID.indexOf("mailview"))
return false;
// Add the button
var add1 = [{title:"Run Agent", find_id: "new", id: "agent1", before: true,
action:"runAnAgent{}", help_text:"Run an agent on the server" }];
addActionsLite( s_MenuID, true, add1);
The preceding code adds a button called "Run Agent". When the user clicks the button, the function
runAnAgent will be called. We'll add this function to
Custom_JS_Lite:
function runAnAgent(sId) {
// Get the UNIDs of the selected documents
var unids = API_GetSelectedDocs_Lite();
// Create an XMLHttpRequest object
if (window.XMLHttpRequest)
{
xhr = new XMLHttpRequest(); // Firefox, Safari, ...
}
else if (window.ActiveXObject) // ActiveX version
{
xhr = new ActiveXObject("Microsoft.XMLHTTP"); // Internet Explorer
}
// Set the function to be called when the request finishes
xhr.onreadystatechange = function()
{
if(xhr.readyState == 4)
{
if(xhr.status == 200) { // success
// Set status message and/or pop up an alert
AAA.EVI.sr (2, "", "Received:" + xhr.responseText, true);
alert("Agent completed");
// Refresh the Inbox
AAA.DSq.ELU(null, 'e-actions-mailview-inbox', 'ESV');
}
else { // error
AAA.EVI.sr (2, "", "Error code " + xhr.status, true);
alert("Error running agent. Error code: " + xhr.status);
}
}
};
// Set the POST params
var sNonce = AAA.HHT ? AAA.HHT() : AAA.getNonce();
var params = "%25%25Nonce=" + sNonce + "&unid=" + unids;
// Send the request
xhr.open("POST", "./?EditDocument&Form=s_RunAgent&PresetFields=AgentName;MyAgent,CommonAgent;2", true);
xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
xhr.send(params);
}
The function first calls the helper function
API_GetSelectedDocs_Lite to get the UNIDs of the selected documents in the view. To use
API_GetSelectedDocs_Lite, we need to remove the comment tags in the following code:
<NotesComment>
//
// ============================================================
// Expose this comment block to include general helper routines
// ============================================================
//
<InsertNotesSubForm Name=API_Utils_Subform>
</NotesComment>
The function then creates an XMLHttpRequest object and uses that to invoke the agent on the server and send the list of UNIDs to it. The agent is invoked by loading the form
s_RunAgent. We tell it which agent to run via the "AgentName" PresetField. The "CommonAgent" PresetField value of "2" means that the agent is in the Extension Forms File.
We send the UNIDs as a form name/value pair. Note that starting in 8.5.2, whenever you do a POST to the Domino server in iNotes, you need to include a nonce parameter. You can get the value by calling the function
AAA.HHT [
com_ibm_dwa_globals.getNonce]. (For 8.5.2 use
AAA.getNonce, because "getNonce" was not obfuscated yet). For versions prior to 8.5.2, you don't need the nonce.
When the server finishes running the agent, it sends a response that causes the onreadystatechange function to get called. We can pop up an alert to let the user know or call
AAA.EVI.sr [
com_ibm_dwa_globals.oStatusManager.addEntry] to add a message to the iNotes console log. If the agent ran successfully, we call this to refresh the inbox:
AAA.DSq.ELU(null, 'e-actions-mailview-inbox', 'ESV') [com_ibm_dwa_globals.oScript.com_ibm_dwa_ui_invokeAction(null, 'e-actions-mailview-inbox', 'com_ibm_dwa_ui_actionRefreshContent')]
Add the server agent
Finally, we'll add the agent to the extension forms file. When we create the agent, make sure to set the following properties:
- Set the agent's target to: NONE.
- Select the "Run as web user" checkbox on the second tab.
For more information about running agents with iNotes, see
Running an agent.
Sub Initialize
Dim ns As New NotesSession
Dim oDocCtx As NotesDocument
Dim doc As NotesDocument
Dim maildb As NotesDatabase
Dim unids As String
Dim subj As String
Dim unidArray As Variant
Set oDocCtx = ns.DocumentContext
unids = oDocCtx.GetItemValue("unid")(0)
unidArray = Split(unids, ",")
Set maildb = oDocCtx.ParentDatabase
ForAll s In unidArray
Set doc = maildb.GetDocumentByUNID(s)
subj = doc.Subject(0)
Call doc.ReplaceItemValue("Subject", "UPDATED: " + subj)
Call doc.Save(True, True)
End ForAll
End Sub
Form values that are posted to a Domino server agent will appear as items in the
DocumentContext object. We get the list of UNIDs as a comma-separated list in the "unid" item. We separate them into an array and get the corresponding
NotesDocument for each one using the
GetDocumentByUNID method. We then modify the "Subject" field and save the document.
And that's all there is to it. For more information on customization of iNotes, see
The basics of iNotes customization.