Working with Multi-Value Date Fields Using the OpenNTF Domino API

I completed a task yesterday that caused me no small amount of grief and wanted to write down what I learned, primarily for myself so I don’t forget, but also to share with others who may be struggling with the transition to using Java in your XPages applications.  I also want to say thank you to the people who offered support, and probably have them and more correct my mistakes. 🙂

Let me set up the scenario.  This task was an enhancement to an existing application I had built at the end of last year.  It was my first successful foray into using Java for all business logic in an XPages application.  Of note, I used the OpenNTF Domino API.  I built it with Bootstrap too, to support both desktop and iPad users.

The application is a task management system.  A task is assigned.  It is followed up on by an individual, and in it they provide proof that they have completed the task.  The task is then assigned back to a supervisor for review.  The supervisor may verify that the task is complete, may indicate that it is tentatively approved for cases where an on-site inspection is required, or may indicate that the proof is insufficient, and assign the task back to the individual.  For cases where the proof is tentatively accepted, it may then either be verified or the task returned.

The enhancement was to track how long it takes for the supervisor to review the proof.  If it is longer than 2 business days the system will note that the supervisor action was within the target period.  It will also track if the action took longer than 2 business days.

I added a date field to track the date that the proof was supplied and another to track when the action was taken, and a third field to track if the action was taken within the target period.  Given that the supervisor could send the task back the requirement was to track each time there was an exchange.  So that meant two multi-value date fields and a multi-value text field.

Anyone who has worked with multi-value Notes date fields and java before will be likely be smiling by now.  Little old me was walking into a blizzard without adequate supplies.  For those of you who can make LotusScript do magical things you can already craft a solution in your head, as did I.  When proof is supplied, grab the first date field, append a value to the field, and save.  When an action is taken, grab the second date field, append a value, grab the text field, calculate and append a value, and save.  We will ignore the fact that in the case of a tentatively accepted proof we don’t have to take the second step when the proof is ultimately verified.

Rather than talk about my struggles I will talk about the solution, other than to say that a Date object in Java is not the same as a DateTime object in Notes, and a Date object in Java is deprecated meaning you should really use a Calendar object, except that it’s okay to use a Date in Java when working in Notes.

The call to use is document.getItemValueDateTimeArray.  Unfortunately, this call returns a Vector<Base<?>> object.  People who have been using Java for a while will be able to explain what this is and why it makes sense.  To a newbie it caused no shortage of pain.  In very simple terms, what is returned is a list of values, as objects.  Those object values happen to be Notes DateTime objects.  The trick is that the compiler doesn’t know that they are DateTime objects.  Naturally the next step is to turn them into DateTime objects, but as I said above we then need to turn them into Java Date objects.

There is some code missing before this step, but this explains what I’ve just said above (it’s the step that reads the values from the field when we first open the document):

    Vector<Base<?>> tempProofSupplied = new Vector<Base<?>>();
    Vector<Date> tempPs = new Vector<Date>();
    tempProofSupplied = docAction.getItemValueDateTimeArray("ProofSupplied");
    if (tempProofSupplied != null) {
        for (Object obj : tempProofSupplied) {
            if (obj != null) {
                DateTime dtPs = (DateTime) obj;

After I figured out the part above, the rest of the code pretty much fell into place.  For example, to add a new date to the list:

    public void trackProofSupplied(Date dateProofSupplied) {
        try {
            if (null == this.proofSupplied) {
                this.proofSupplied = new Vector<Date>();
        } catch (Exception e) {
            System.out.println(" ERROR ! action.trackProofSupplied: " + e.toString());

I also want to say a big Thank You to Frank Van Der Linden who posted a snippet of Java Date utilities to OpenNTF, including one very useful function: calculateBusinessDays.  Saved me having to figure that one out myself.  Fair warning: it includes Calendar objects that I hadn’t used in the code above.  Calendars are really useful by the way, and worth investing the time to understand if you haven’t yet.


I am an IT professional with over 20 years of experience. For much of that time I have worked with IBM Lotus Notes and Domino, helping organizations take full advantage of the tool for building workflow collaboration solutions. I have ITIL certification and a background in project management as well. Recently I have invested in how mobile devices may be used to extend business applications outside the office, and have also been learning how to add social components to traditional business applications. Away from work, I have three daughters and recently celebrated my 20th wedding anniversary with my wife in Hawaii. I coach hockey, cycle, and love growing garlic and then finding new ways to use it. I added a section of herbs to my garden last year and was very happy with the result. I ride my bike each year with my wife in the Ride to Conquer Cancer to raise money for research in childhood cancers, particularly brain tumours. Our youngest daughter lost her battle with a brain tumour in 2008 and through this ride we hope to help find a way to prevent other families from experiencing what we went through and continue to live with. If I have any spare time, I like to travel, so you may see the odd photo from our family adventures here too.

Posted in Uncategorized
One comment on “Working with Multi-Value Date Fields Using the OpenNTF Domino API
  1. Good to hear, my DateUtils class was useful to you

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: