A PlaceBot is an agent written in LotusScript® or Java™ that can perform a task and can manipulate data in a place. This article explains how to create a LotusScript agent, export it to an .lss file, create the PlaceBot and import the .lss file, and manage the PlaceBot.
You can use a PlaceBot to automate tasks such as accessing, processing, and managing data in a place. For example, you can use a PlaceBot to send an email when a page of a certain type is submitted, on a scheduled basis or manually.
Here, we create a LotusScript agent using IBM Domino Designer Client, export the agent to an .lss file, and then import it into IBM Lotus Quickr as a PlaceBot.
Prerequisites
This article assumes that you are familiar with LotusScript. For more information, consult the
Lotus Domino Designer 8 Help.
You can set PlaceBots to run on a schedule or run when a particular form is submitted. You can also set a PlaceBot to run manually, but you must have Manager access to the place to create, edit, copy, delete, or run PlaceBots manually.
Creating a PlaceBot using LotusScript
Let’s now walk through the following four basic steps to creating a PlaceBot using LotusScript:
• Creating a LotusScript agent
• Exporting it to the .lss file
• Creating a PlaceBot and importing the .lss file
• Managing the PlaceBot
Creating a LotusScript agent
We use the Lotus Domino Designer to create an agent, as follows:
1. Open the Lotus Domino Designer Client; you can launch this by running the designer.exe file in the Lotus program directory.
2. Create a blank database, using File Application New, from the menu.
3. Enter the Title, select the “-Blank-“ template, and then click OK (see figure 1).
Figure 1. New Application dialog box
4. Expand the Shared Code section and then select Agents (see figure 2).
Figure 2. Design Agents
5. Click the New Agent button, as shown in figure 3.
Figure 3. New Agent button
6. Fill in the Name field, leave the default settings for everything else, and close the Agent dialog box (see figure 4).
Figure 4. Agent dialog box
7. Select LotusScript from the drop-down menu on the right-hand side and then select Initialize from the Objects tab in the middle section (see figure 5).
Figure 5. Initialize IBM agent
8. Add the LotusScript code below. This code selects the current document, grabs the Subject and Author of the document, and sends out an email with that information. It also stores output in the agent log and fails, if there is no current agent running.
To display an agent log, select the agent and choose Agent - Log. Also, be sure to enter the email ad dress correctly.
Sub Initialize
'This agent gets the document context and changes its subject.
Dim session As New NotesSession
Dim db As NotesDatabase
Dim doc As NotesDocument
Dim subj As Variant
Dim author As Variant
Dim item As NotesItem
Dim memo As NotesDocument
Dim recipient As String
'This method stores output in the agent log and fails if there is no current
‘agent running. To display an agent log, select the agent and choose Agent ‘- Log.
Dim agentLog As New NotesLog( "IBM Agent" )
Call agentLog.OpenAgentLog
'Get the page being published and log the UNID
Set doc = session.DocumentContext
Call agentLog.LogAction("Current Document UNID: " + doc.UniversalID)
'Get the subject and log the subject value
subj = doc.GetItemValue( "h_Name" )
Call agentLog.LogAction("Subject: " + subj(0))
'Get the Author and log the author value
author = doc.GetItemValue( "h_Authors" )
Call agentLog.LogAction("Auhtor: " + author(0))
'Get the current Database
Set db = session.CurrentDatabase
'Create a memo document
Set memo = db.CreateDocument
'Set the subject
memo.Subject = "Following Post was submitted: " + subj(0)
'Create Body item
Set rtitem = memo.CreateRichTextItem( "Body" )
'Appending Text to Body of the memo
Call rtitem.AppendText( "Post was submitted" + Chr(13) + Chr(10))
Call rtitem.AppendText( "Subject: " + subj(0) + Chr(13) + Chr(10))
Call rtitem.AppendText( "Auhtor: " + author(0) + Chr(13) + Chr(10))
recipient= "
EMAIL_ADDRESS"
'Sending mail and log
Call memo.Send(False, recipient)
Call agentLog.LogAction("Mail Sent to " + recipient)
Call agentLog.Close
End Sub
9. Save the agent.
Exporting to the .lss file
Export the LotusScript agent we just created:
1. Open the agent in Lotus Domino Designer.
2. Export the agent to the .lss file by using File Export, and saving it with an .lss extension (for example, myagent.lss).
Creating a PlaceBot
Create a PlaceBot and import the .lss file created previously.
1. Log into a place and select Customize this place (see figure 6).
Figure 6. Customize this place
2. On the Customize screen, select PlaceBots (see figure 7).
Figure 7. Customize the place
3. Click the New PlaceBot button (see figure 8).
Fig u re 8. New PlaceBot button
4. Fill in the information in the New PlaceBot dialog box (see figure 9):
a) Give it a title.
b) Enter a description for the PlaceBot.
c) Select to run the agent based on when a form is submitted or on a scheduled basis.
d) Click the Folder button to browse for the .lss file.
e) The last field is used to provide a base class name if you are using multiple Java files.
Figure 9. New PlaceBot dialog
5. Click the Done button; your PlaceBot is now created and ready to use.
Managing the PlaceBot
You can copy, delete, run, sign, and display log information about PlaceBots. To get to these settings, use Customize PlaceBots, and click the More Actions button (see figure 10).
Figure 10. More Actions
To edit the PlaceBot, you can just click on it.
Copy PlaceBot. Copies the PlaceBot to a room you specify. If you are copying a form PlaceBot to a new room, you must associate the PlaceBot with a form in the room. This is not done automatically as part of the copy-ando-paste procedure.
Delete PlaceBot. Deletes the PlaceBot
Run PlaceBot. Runs the PlaceBot manually.
Sign PlaceBot. Signs the PlaceBot using the current user’s name. You must have Manager access to the place to create, edit, copy, delete, or run PlaceBots manually.
PlaceBot Log. Opens the PlaceBot log. The log displays information from the last time the PlaceBot ran and any log statements you may have included in your PlaceBot code. (The sample code above has an example of how to write to the agent log.)
Conclusion
PlaceBots are a good way to automate tasks and manage the data in a place. You can run them on a schedule or when a form is submitted and can use a schedule-based PlaceBot to do cleanup or create reports for your place. You can also use the PlaceBot to modify the data or send a notification when a form is submitted.