Notes 6 agents introduced the ability to run a client agent in a background thread. This is a very powerful feature, but you have to know how to properly use it. First off, you cannot perform any UI tasks. However, this is not a drawback. Print statements do work - the results go to the status bar just like any other agent running on the client. The MessageBox LotusScript statement also works. A message will be popped up for the user, and you can proceed in your agent based on the answer (your agent waits until the box is clicked).

So you can interact with the user. You could not perform the NotesUIWorkspace.Prompt method (because it's a front-end class method, and no front-end classes are allowed). What about finding the current document? Well, using back-end classes, you can find out what document is opened in the UI. Under the NotesDatabase class, there is an UnprocessedDocuments method. If you kick off a script when a document is opened (either in read mode or edit mode) the UnprocessedDocuments method will return a NotesDocumentCollection object with only one document in it - the currently opened document. So you can run the agent against just the opened document.

How do you set up an agent for background processing? First, the agent has to be available to the Actions menu. I don't know why that requirement is there, but it is. Next, you click the check box on the Agent Properties box called "Run in background client thread". This will set up the agent for running in the background when kicked off by the client.

What's the benefit? The user's client is freed up for other things. The agent is running in the background - you'll see a change in your status bar. (For those of you that are Battlestar Galactica fans, it reminds you of a Cylon with the task bar going back and forth). You can use your Notes client to check your mail, go in to other databases, all kinds of stuff. You can run multiple agents in the background - the status bar is stacked. You can do anything in that agent (with the exception of the NotesUI classes) that you can in the foreground. This includes things like opening up Excel to create reports.

Are there any gotchas? A couple minor ones. Since the agent has to be in the actions menu, you probably want to do a little "environment check" at the start of the agent, depending on what you're doing. For example, if you're wanting to run on only the currently opened document, then you should have a computed for display field on your document. (Since it is computed for display, it is not saved with the document, so it will only be available when the document is opened). If it's not the right environment, then you can display a message and exit the agent.

When we use background agents, we have gotten into the habit of putting up a message box at the start of the agent and at the end of the agent, simply for "usability". The one at the start tells the user their request is processed in the background and they can check their status bar for updates. We include lots of Print statements while the agent is running. We found that at least until users get used to background agents, they tend to start something off, then see that their Notes client is available, then think "Hmm, where's the results?". The message box telling them the agent is running in the background helps. The message box at the end tells them everything is done and they can check the results.

One final warning... If you are doing something like building a report in Word or Excel, keep in mind that multiple agents can be kicked off. Each is going to have its own thread in Notes, but when you start dealing with external applications it is possible to cross lines. So make sure you open up your own instance and make sure you close your own instance. Just make sure to do your testing by kicking off multiple background agents to make sure everything works.