Sunday, January 21, 2007

Notify database responsible person about new documents using Sametime

Imagine that you are responsible for a Domino application where users can register themselves and you want to get notified about about new registrations as soon as possible.

Screenshot of the demo application:
reg db demo

This can be done by sending an email message in WebQuerySave event or SMS message, but it has its disadvantages. Sending by email can give several minutes of delay, and receiving 20 SMS per hour can be annoying. Using Sametime messages for notification is not as disturbing as beeping SMS messages and also ensures instant delivery.

One more way to see the latest registrations is to use a Sametime bot to get a quick overview of the latest registrations without opening the database in Notes client.

Let's see how you can use tools provided by Botstation Technologies (all available as free trial) to accomplish these tasks.
1) Immediate notification when user saves his registration
2) Course administrator gets latest results by asking Sametime bot

Immediate notification
To immediately notify the responsible person about new registration, all you need to do is add a couple of code lines into your WebQuerySave agent. The code uses STAgent script library, which contains the most popular functions for working with Sametime. You can easily send a Sametime message to the specified person:
Here is an example:
Dim STAgent as New STAgent()
Call STAgent.login("", "Notification Agent", "password")
Call STAgent.sendMessage("Admin Doe", "New registration: "+doc.CourseDate(0)+" / "+doc.CreatedBy(0)+" / "+doc.Subject(0))
Call STAgent.logout()

The recipient immediately gets a Sametime message showing registration details and can take an appropriate action if needed.

If you have several responsible persons and want to send the notification message only to one of them, you can send the message only to the first person whos Sametime online availability status is set to Active. You can query the online status with this code line:
onlinestatus=STAgent.getOnlineStatus("Admin Doe") 'Active, Away, Offline

You can download an evaluation version of the STAgent and try by yourself in your own agents.

Notification on demand
Instead of sending a Sametime message immediately after each registration, you can query Sametime Bot to get the new registrations since last the query time. Sametime Bot from our company Botstation Technologies is able to run ordinary LotusScript agents, which makes it possible to accomplish this task in just 5 minutes. Same solution can be re-used later in similar applications. You can also restrict access to this particular bot functionality to only certain persons.

"Access properties" screenshot:

Sametime bot security

To ask bot for new registrations, you simply choose bot from your buddy list and type "registrations" to him. Bot receives your message and immediately answers with a list of last registrations.
To make this work, all you need to do is to create a LotusScript agent which searches for documents created after agent's last run time and then create a Question mapping in the bot's configuration database.
To create a bot question which triggers an agent, you specify keywords (e.g. "registrations", "bookings") and choose an agent from a list of available agents. See the picture below.

Sub Initialize
Dim s As New NotesSession
Dim agent As NotesAgent
Set agent = s.CurrentAgent
Dim db As NotesDatabase
Dim doc As NotesDocument
Set db = s.CurrentDatabase
Set doc = db.GetDocumentByID(agent.ParameterDocID)
tmp= AgentMain(doc)
Call doc.Save(True,False)
End Sub

Function AgentMain(doc As notesdocument) As String
Dim session As New NotesSession
Dim db As NotesDatabase
Dim coursedb As notesdatabase
Dim coll As NotesDocumentCollection
Dim coursedoc As NotesDocument
Dim agent As NotesAgent
Set db=doc.ParentDatabase
Set coursedb=New NotesDatabase(db.server, "coursereg.nsf")
Set agent=session.CurrentAgent
Set dateTime = New NotesDateTime(agent.LastRun )
Set|Form="Document"|, dateTime, 0)
Set coursedoc=col.GetFirstDocument
tmp="No new registrations found since "+Cstr(agent.LastRun)
If col.count>0 Then tmp="Found "+Cstr(col.count)+" new registrations since"+Cstr(agent.LastRun)+"<br>"

While Not coursedoc Is Nothing
tmp=tmp+coursedoc.CourseDate(0)+" / "+coursedoc.CreatedBy(0)+" / "+coursedoc.CourseName(0)+"<br>"
Set coursedoc=col.GetNextDocument(coursedoc)

End Function

I've created a live demonstration of this functionality using the code above, you can try it here: live demo of Sametime bot reading the registration database

To emulate the real application, the bot in the demo application adds a random number of new documents (1-5) after each run. So every time you issue "registrations" command to bot, you will get some unique results.

Sametime bot answers