Soft-code item names to facilitate LotusScript management

The simplest way to access items created with forms is to hard-code item names. But this presents a few problems. Learn how soft-coded items in LotusScript are easier to maintain and less prone to errors.

A common task in LotusScript is adding or updating items (fields) in Lotus Notes documents. There are several different ways to update values in a Notes item, but the method you use will determine whether or not your code is easy to maintain.

This tip demonstrates how to use soft-coded item names and how they generate LotusScript code that's easier to manage and causes fewer errors.

The WorkOrders - Form below shows how you could use items stored in documents that were created with a form (Figure 1).


The simplest way to access items created with the WorkOrders form is to hard-code item names. For example:

doc.Location = "Paris"
doc.ReplaceItemValue( "Status", "Open")

Although this code customizes the form, it also presents you with two potential problems.

  1. Item names may be misspelled.
    doc.Pocation = "Paris"
    doc.ReplaceItemValue( "Ztatus", "Open")

    If item names were typed incorrectly, as shown above, Domino Designer would save the code and run without error. However, the compiler cannot check whether or not the item name is actually valid.

    When the code runs, it creates a new item on the document called Ztatus that has an Open value. It does not update the existing field as Status. Similarly, a new Pocation item would be created with a value of Paris, instead of updating the item correctly.

  2. More Lotusscript resources:
    30 LotusScript tips

    LotusScript agent automates selective mail file replication

    How to create mail files using a LotusScript agent

  3. Item names may change. Even if you enter item names correctly, you may encounter a situation in which the item name is changed on the form.

Using the previous code example, suppose that you needed to change the name of the Location item to Region. If so, you would need to search for every occurrence of Location within your LotusScript code, including forms, pages, agents, script libraries, etc. You then would have to change every occurrence to the new item name. Then, you'd need to retest all of the modified code.

Soft-coding item names can solve both of these problems. Soft-coding an item means that its name is stored as a variable in your code. Soft-coded item names are best stored in constants. For example:

Const FN_LOCATION = "Location"
Const FN_STATUS = "Status"

Note: Constants start with FN_ to identify them as field names. I also recommend using capital letters for constant names. But you can use any naming convention you want.

Once constants are set, you can use them to access the Notes item, instead of using the hard-coded item name. For example:

doc.ReplaceItemValue(FN_STATUS, "Open")

Using the constant in the ReplaceItemValue instead of the hard-coded item name ensures that you're using a valid field name. If you try to use a constant that doesn't exist, you'll receive a compile-time error when saving the LotusScript code because the constant is undefined.

doc.ReplaceItemValue(FN_ZTATUS, "Open")

Trapping the error while at this point is better than encountering it during runtime; you can resolve issues before they get to a testing or production environment.

If the name of the item changes, you only have to change the item once in the constant, rather than changing every occurrence of it in the code.

Note: When using constants, you can't access the item name as a property of the document. For example, the following code would not work:

doc. FN_STATUS = "Open"

A good way to implement the item name constant is through a script library. I recommend creating a separate script library to retain item names for each form. You can create a script library called Fields_WorkOrderForm and place the following code in the Declarations section of the library (Figure 2).


I used the constant FN_WORKER for the item AssignedTo. This is an example of how you can name constants different than the actual item name when it makes sense to do so. You may want to use this approach for long item names or in cases where the item name changes.

With the script library in place, any code that works with fields from the WorkOrders form needs to include the script library with the LotusScript "Use" statement (Figure 3).

the script library in your 'use' statement

By re-using the script library, you can ensure that all LotusScript code in an application uses one set of item constants. Any changes to an item name only need to occur in the script library.

Using soft-coded item names may take a while to get used to. And while it also requires extra LotusScript coding, the benefits of ensuring that item names are valid and the ease of manageability outweigh the effort involved.

Ethann Castell
Ethann Castell is a senior consultant with Caliton Innovations. He has extensive experience across all aspects of Lotus Notes and Domino dating back to 1995. Caliton Innovations develops leading-edge Lotus Notes tools, and provide boutique consulting services. You can contact Caliton Innovations through their Web site at

Dig Deeper on LotusScript

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.




  • iSeries tutorials's tutorials provide in-depth information on the iSeries. Our iSeries tutorials address areas you need to know about...

  • V6R1 upgrade planning checklist

    When upgrading to V6R1, make sure your software will be supported, your programs will function and the correct PTFs have been ...

  • Connecting multiple iSeries systems through DDM

    Working with databases over multiple iSeries systems can be simple when remotely connecting logical partitions with distributed ...