Providing configuration document for DOTS tasklets

Flexibility is always welcomed when it comes to configuring apps – or DOTS tasks in this case. A database is the usual route to store preferences that will determine their behaviour. It might be easy to set this up with a XPages applications, a little less so for a DOTS tasklet. What might immediately come to mind would be to hardcode the database coordinates the task will use to look up for the configuration settings. However, that would be limiting, for such approach would force every single deployment of the DOTS tasklet to follow that pattern (specific replica ID, database path or else). Fortunately, that is not necessary.

DOTS provides an extension that allows for a more manageable configuration. All we need to do is to add the extension com.ibm.dots.configuration:

Here’s the XML counterpart:

<?xml version="1.0" encoding="UTF-8"?>
<?eclipse version="3.4"?>
<plugin>
   <extension
         point="com.ibm.dots.task">
      <task
            class="com.matika.dots.watchmail.WatchmailTask"
            description="Watchmail"
            id="WatchmailTask"
            runOnStart="false">
				<run every="5" unit="minute"></run>
      </task>
   </extension>
   <extension
         point="com.ibm.dots.configuration">
      <initializer
            class="com.matika.dots.watchmail.Initializer">
      </initializer>
      <form
            dxlpath="res/configuration.dxl">
      </form>
   </extension>

</plugin>

The extension requires 2 parameters:

1. initializer: the class that enables to provide default values for the configuration profile document that will be created, or modified if necessary.
2. form: the form – in its dxl form – the configuration document will be opened with.

The Initializer

The initializer is a class that must extend the AbstractConfigurationInitializer class. Such class must then extend the initializeDefaultConfigurationParameters method. The code is quite straightforward:

package com.matika.dots.watchmail;

import com.ibm.dots.preferences.AbstractConfigurationInitializer;

import lotus.domino.Document;
import lotus.domino.NotesException;

public class Initializer extends AbstractConfigurationInitializer {

	@Override
	protected void initializeDefaultConfigurationParameters(Document paramDocument) throws NotesException {
		// com.ibm.dots.internal.preferences.IPrefConstants.FIELD_PREF_PREFIX
		String fieldName = "pref_" + "database_path";

		if (!paramDocument.hasItem(fieldName)) {
			paramDocument.replaceItemValue(fieldName, "server!!config.nsf");
		}
	}

}

The profile document used for the DOTS tasklet is passed to the initializeDefaultConfigurationParameters method. With that we can make sure default fields are created along with their default values.

The Form

The form is a parameter that could be omitted. In such case DOTS would use the default form that can be found in the com.ibm.dots plugin. See the screenshot below:

What the form looks like when opened from DDE:

Actually there’s nothing bad about the default form. It works and it’s flexible in that, for every row – name=value – of the DisplayPreferences field, a document field will be created and managed automatically. However it’s as user friendly as it can be: no input facilitation or contextual help can be provided in this way. What you see is just a textbox field.

At this point we decide the default form is not enough so we take the source code and start customize it with the good bad old DDE to any like we want. For example like this:

Once our form is ready, we copy the whole dxl source code and paste it in a newly created plugin folder that we can name whatever name we want. In this instance I am going for the default naming convention provided by the com.ibm.dots plugin. Also, the file name is not important, granted the extension used for it remains dxl (see note below).

The last fundamental step is to include the newly created folder in the binary build. If that is not done, the form won’t be included in the jar and therefore it will be unavailable to DOTS that in turn will revert back to the default form.

The result

When the DOTS tasklet will be loaded a new response document will be created under the DOTS profile it is running under. The configuration document will display the data by means of the form we composed.