How to create whitehat viruses in Lotus Notes (or, I don't *need* you to click on my buttons anymore)!

11/04/2009 11:58 AM by Chris Toohey

I find that more and more people are unfamiliar with the following technique, which I've found both extremely useful for addresses individual issues that arise as well as can greatly limit the Mail Template design customization which can ultimately impact Lotus Notes Domino functionality and/or IBM support.

How many times have you created an email with a Button, which you've coded with Formula or - hopefully - LotusScript that's been designed to perform some function?

And how many times do people just ignore those emails? Sure, they open the email once, but they never click on your button for whatever silly reason they have. Ultimately, you're hard work is ignored and didn't get the chance to do whatever you wanted/needed it to do.

Well to hell with that! Ignore my directions?! Face the wrath of my Stored Forms!!

... okay, sorry. I took the users ignoring my beautifully crafted button code personally.

At the end of the day, the silly user ignored your hand-crafted code-poetry, and the issue that you intended to address is - I'll presume - still an issue. Sneakernetting - the act of getting out of your chair and walking to the user to fix the issue (or click on the damned button for them!) - should be your last resort. Sometimes that's not even possible (read: remote sales force). So how do we address the issue?

We create a "virus". It's okay, m'am, I'm from the internets and will have my name listed in the user's Lotus Notes Client ECL, not to mention that it's not a "virus" as much as it's a viral-type event that will run your code as soon as the user opens the email.

I do this all of the time, and most recently used this technique to call a Java Agent in a commonly accessible NotesDatabase that triggered an OS xCopy of files to a network drive... all without the user's knowledge or input/action (outside of them opening the email).

The Technique

Here's the overview:

1. We will be creating a new Mail Database which can be stored either locally or on your Domino Server, based on your Domino server/commonly-used Mail Template.
2. We will modify the Memo Form Design Element to handle our functional payload.
3. We will send an email from our new Mail Database to our intended recipient.
4. On the PostOpen event of the Memo Stored Form, we'll execute the functional payload.

Pretty simple stuff really. There are no recipient template modifications. There are no customization to anything outside of your new Mail Database, which can be thrown away after it's performed it's function.

See - this technique relies on the way that Lotus Notes Domino Messaging (and NotesDocument routing) works.

The short, short, short version of that fundamental function in Lotus Notes Domino is this:

Typically, an email message contains no UI rendering information, but rather only data via NotesItems in the given NotesDocument. For visual representation, we check the NotesDocument Form NotesItem to see what Form Design Element we should use to render the NotesDocument. If that NotesItem doesn't exist, or the value of the Form NotesItem doesn't match a Form Design Element in the target NotesDatabase, it will attempt to use the Default Form Design Element. If there is no match and there is no Default Form Design Element, the user will get an error when they try to open the NotesDocument.

A Stored Form stores the rendering design information in the NotesDocument. And while this makes the NotesDocument much larger than it's non-Stored Form counterparts, it will allow you to control not only the visual rendering of the NotesDocument in a "remote" NotesDatabase, but it will also allow you to completely control the Form Events (QueryOpen, PostOpen, etc.) and any code executed therein.

See where I'm going with this?

Step 1: Create a new Mail Database

This one's easy. Create a new Mail Database, based on your company's standard Mail Template, and disable Design Inheritance from said Mail Template.

Step 2: Customize the Memo Form Design Element

You'll want to make sure that you do the following when customizing the Memo Form Design Element:

1. Remove all Computed Subforms. You won't need them, and it'll throw an error with the Stored Form design.
2. Modify the PostOpen Event (or whichever Form Design Element Event you're using) to account for you opening the Memo Form Design Element as a New Memo. source.IsNewDoc or checking for the PostedDate NotesItem value will work here nicely.
3. In the Form Design Elements Properties, select Store form in document.

Using the PostOpen Event of your Memo Stored Form, you can now use LotusScript to call whatever functions you'd like!

Here's an example of me calling my xCopy application - which copied a number of NotesTemplates from a common network share to the local machine - and replacing the Personal Address Book Design for the user:

If Not(source.IsNewDoc) And Not(source.EditMode) Then
  Dim s As New NotesSession
  Dim xdb As NotesDatabase
  Dim xagent As NotesAgent

  Set xdb = s.GetDatabase(ITserver, "xcopy.nsf")
  Set xagent = xdb.GetAgent("xcopy")

  If (xagent.Run = 0) Then
    Call ReplaceDesign("", "StdR4PersonalAddressBook", "", "names.nsf")
    Call source.Close()
    Call source.DeleteDocument
  End If

End If

The copy, replacing, and deletion of the virus email was triggered - and here's the beauty - once the user opened the email. Buttons? No thanks, I'm covered! ;-)