THE VIEW 2008 Technical Supplement / Sametime blackboxes

Thank you for reading my piece on custom Sametime blackboxes in THE VIEW 2008 Technical Supplement. The piece is very short but should help you get the basics on using custom Sametime blackboxes. If it didn’t don’t worry. A full length article on the same subject will appear in the regular THE VIEW magazine in the beginning of 2008. It might already have been published when you read this.

Please note: With the release of Lotus Connections 2.0 the database schema has changed slightly. To make sure the blackbox works with LC 2.0 see this post for the updated SQL.

Now for the shameless plug! 😉

If you need assistance with Sametime installation, development, consulting or simply have a question regarding the Lotus portfolio please contact me and we’ll have a chat. Either send me an e-mail (mh [at] or see if I’m on Skype.

Example code

The article mentions an abstract blackbox base class you can extend. You’ll find the code and the database in the download at the bottom of the page. Below is an example of how to use the abstract base class.



import java.util.Collections;
import java.util.HashMap;
import java.util.Map;


import lotus.domino.Database;
import lotus.domino.Document;
import lotus.domino.NotesFactory;
import lotus.domino.NotesThread;
import lotus.domino.Session;
import lotus.domino.View;

public class PhonebookBlackbox extends AbstractBlackbox {

   protected Map loadValues(String user_id, String[] details)
      throws Exception {

      try {
         // declarations
         Map m = new HashMap();

         // initialize Notes environment and create session
         Session session = NotesFactory.createSession();

         // get database and view
         Database db = session.getDatabase(null, "phonebook.nsf");
         View view = db.getView("lookupPersonByEmail");

         // lookup user
         Document doc = view.getDocumentByKey(user_id, true);
         if (null != doc) {
            m.put("MailAddress", user_id);
            m.put("Name", this.getValue(doc, "PersonFirstname") +
                  " " + this.getValue(doc, "PersonLastname"));
            m.put("Title", this.getValue(doc, "PersonTitle") +
                  " (" + this.getValue(doc, "PersonDepartment") + ")");
            m.put("Telephone", this.getValue(doc, "PersonPhone"));
            m.put("Company", this.getValue(doc, "CompanyName"));

            // get image
            EncodedImage img = this.encodeImage(session, 
               doc, "Picture");
            m.put("Photo", img);

            // return map
            return m;
         } else {
            return Collections.EMPTY_MAP;
      } catch (Throwable t) {
         throw new Exception(t);
      } finally {

   private String getValue(Document doc, String name)
      throws NotesException {

      return doc.getItemValueString(name);

Downloadable code

Below are the links to the downloads for the article. The file contains the sample phonebook database (phonebook.nsf). The file contains the abstract base class that I use in the code example that makes it much easier to write your own blackbox. The code is an Eclipse project ready for import into Eclipse.