Are you one of those people who haven't gotten away from the workspace in Notes 5 or 6? If so, you've probably come to love the little icons on each of the databases. This tip shows you how to programmatically change the icon using LotusScript by creating a nightly agent, so each day your users will have a new icon to see. You could even set it up so the icon is changed every time you open the database. Think this is stupid? I can tell you from experience that implementing this makes users want to go into the database. They want to see what the "icon of the day" is, and then they end up reading information in the database.

There are three things you'll need to know in order to change the database icon. First, you need to know that the icon is actually a Notes document (just like every design element) so it can be manipulated like any Notes document. Second, the actual picture is stored in a special field called IconBitmap. Third, you need to know the location (in the database) of the icon so you can get it and manipulate it. That location varies from database to database. There are ways in Notes 4 and 5 to find the location programmatically using the Notes API. Notes 6 introduced a new way using the new NotesNoteCollection class. But that is actually overkill for this exercise, because the location of the icon, once the database has been created, is fixed. So you just need to look it up once and set the value. If you want to make this script generic and portable, then you can look into dynamically getting a handle to the icon document. But here we'll just look it up once and leave it at that.

To look up the location of the icon document, in Notes 5 go to Resources\Other in the designer client, or in Notes 6 go to Other\Database Resources. Highlight the icon (don't double-click on it like you were going to edit it) and go to Design Properties. Go to the last tab (the "beanie") as seen in figure 1, and make a note of the document ID (the value starting with "NT"). This is a hex value, and this is the location of the icon document within the database. That's what you'll need to get a handle to the design element as a document.

Next, you'll need some source database icons in the right format. (That IconBitmap field is a special format, so you need to duplicate that). Luckily for you, I've done the work and you can with 103 different icons. To create each icon document, first you need to set the database icon to what you want. Then you run an agent that captures the special IconBitmap field and stores it in a true Notes document (not a design element document). Note that this special field can't be viewed in any way, so really you don't need an underlying form to display the documents. But the sample database does have an underlying form that can be used to add a title to the document and has a rich text field where you can paste the graphic if desired (you can actually see the icon). Here's the agent that builds a new document from the current database icon:

Sub Initialize
   Dim session As New NotesSession
   Dim db As NotesDatabase
   Dim iconDoc As NotesDocument
   Dim newDoc As NotesDocument
   Dim item As NotesItem
   
   Set db = session.CurrentDatabase
   Set iconDoc = db.GetDocumentById("13E")
   Set newDoc = db.createdocument
   Call newDoc.ReplaceItemValue("Form", "frmIcon")
   Call newDoc.replaceItemValue("Descr", "(undescribed)")
   Set item = iconDoc.GetFirstItem("IconBitmap")
   Call item.CopyItemToDocument(newDoc, "IconBitmap")
   Call newDoc.Save(True, True, True)
End Sub

The value "13E" is the hex location of the icon design element in the sample database. It most likely will be different in each database. This agent finds that design element, then copies the IconBitmap field into a new document (regular document, not a design element). The new document gets a form field and a description field. These are done just so the document can appear in views, as it does in the sample database. The document doesn't have to appear in views if you don't want it to.

Once you have the documents built, it becomes a matter of swapping out the IconBitmap field on the actual icon design document with the same field on one of these pre-populated documents. The sample database has an agent that swaps the icon on the current database with the icon stored in the selected document.

To create an "icon of the day" scheduled agent, you'll want to first have the database of icons somewhere that the scheduled agent can access. In Notes 5, it has to be on the same server as the scheduled agent. In Notes 6, scheduled agents can access other servers as long as they are trusted, so the database could be on another server. The scheduled agent finds the icon design note, then randomly picks a new icon and replaces the IconBitmap field. Here's an agent that does the work:

Sub Initialize
   Dim session As New NotesSession
   Dim currDb As NotesDatabase
   Dim iconDoc As NotesDocument
   Dim iconDb As NotesDatabase
   Dim iconColl As NotesDocumentCollection
   Dim iconPos As Long
   Dim newIconDoc As NotesDocument
   Dim item As NotesItem
   
   Randomize
   Set currDb = session.CurrentDatabase
   Set iconDoc = currDb.GetDocumentById("11A")
   If iconDoc Is Nothing Then Exit Sub
   Set iconDb = session.GetDatabase("", "icons.nsf")
   If iconDb Is Nothing Then Exit Sub
   Set iconColl = iconDb.AllDocuments
   If iconColl Is Nothing Then Exit Sub
   iconPos = Int(Rnd() * iconColl.Count)
   Set newIconDoc = iconColl.GetNthDocument(iconPos)
   If newIconDoc Is Nothing Then Exit Sub
   If Not newIconDoc.HasItem("IconBitmap") Then Exit Sub
   Call iconDoc.RemoveItem("IconBitmap")
   Set item = newIconDoc.GetFirstItem("IconBitmap")
   If item Is Nothing Then Exit Sub
   Call item.CopyItemToDocument(iconDoc, "IconBitmap")
   Call icondoc.Save(True, True, True)
End Sub

Note that "11A" is the icon location in the database I'm changing on a nightly basis, and "icons.nsf" is the path to my source "Icons Of The Day" database (the sample database). The agent randomly picks an icon from all the available source icon documents, and then replaces the special field in the current database's icon design element with the same special field from the source document.

Enjoy changing your database icon on a nightly basis!