1. technology and computing
2. programming languages
3. javascript

Type of Submission: Article
Title: IBM Case Manager
Subtitle: Supporting Display of Long Date Format in ICM 5.2.1 using a Custom
Plugin
Keywords: scripts, customizing, widgets
Author: Chad Lou
Job Title: Senior Software Engineer, IBM Case Manager and Enterprise Content
Management
Email: chadlou@us.ibm.com
Bio: Senior Software Engineer of the IBM Case Manager Client.
Company: IBM
Contributor: Brent Taylor
Job Title: Senior Software developer, IBM Case Manager Client
Email: bataylor@ca.ibm.com
Bio: Developer of the IBM Case Manager Client action framework.
Company: IBM
Contributor: Brett Morris
Job Title: Architect, IBM Content Navigator
Email: bwmorris@us.ibm.com
Bio: Architect of IBM Content Navigator product
Company: IBM
Contributor: Lauren Mayers
Job Title: Architect, IBM Case Manager
Email: lmayes@us.ibm.com
Bio: Architect of the IBM Case Manager product
Company: IBM
Contributor: Yajie Yang
Job Title: Development Manager, IBM Case Manager
Email: yajieyang@us.ibm.com
Bio: Development Manager of the IBM Case Manager product
Company: IBM
Abstract: This article describes a custom plugin to display long date format in IBM Case
Manager client application.
Supporting Display of Long Date Format in ICM 5.2.1 using a
Custom Plugin
Chad Lou, Brent Taylor, Brett Morris, Lauren Mayes, Yajie Yang
Introduction
IBM Case Manager (ICM) is a web-based solution that helps customers streamline the
creation and management of case workflow. ICM 5.2.1 is built on the IBM Content
Navigator (ICN) framework.
Many customers have required the ability to display dates in long format. The ICN team
designed and provided a plugin, which essentially redefines valueFormatter to use a long
format as the default in ICN. This enhancement works for ICN widgets as well as ICM
widgets based on or which extend from ICN widgets. These ICM widgets are:
- In-basket
- Case Doc
- Case List
However this plugin has no effect for dates in other places of ICM such as:
- Case Information (Properties widget)
- Case History
- Case Comment
- Case Toolbar
- Case History Visualizer (CHV)
One solution is to modify ICM code to display dates using ICN mechanism. However, the
requirement came after ICM 5.2.1 is released. Aligning ICM with the ICN mechanism
will be done in a future release. In the meantime, for ICM 5.2. 1, we still need to address
this customer requirement. Also, dates are displayed in more than one way in ICM today,
so enhancing ICM to be more consistent with ICN does not fully address all areas where
dates are displayed. This article discusses an approach to provide the support by way of
extending the custom plugin.
Existing ICM Mechanism of Displaying Date/Time
Let’s first look at how ICM displays Dates in ICM 5.2.1.
ICM by default uses the short date format to display dates in our widgets. The Case
History Visualizer (CHV) widget uses the medium date format, since the timeline field
has limited width and must accommodate a varying amount of information.
ICM has centralized the mechanism of displaying time format for ICM widgets in ICM
5.2. All time displaying routines go through icm.util.Util.js.
There are 2 functions involved in displaying date/time in ICM.
1. formatLocaleDate
2. getLocaleDate
These functions are defined in icm/util/Util.js.
/**
* get the date string based on format and plugin locale
* primarily for CHV use
* @private
* @param date (object) or a UTC timestamp (string)
*
a javascript date object
* @param format (object)
*
an object with date formatting settings
* @return the text for displaying the date
*/
formatLocaleDate: function(date, format) {
if (!date) {
return "";
}
if (typeof date == "string") {
// assume date is a UTC stamp string
date = dojo.date.stamp.fromISOString(date);
}
format.locale = ecm.model.desktop.valueFormatter.getLocale();
if (format.locale == "ar" && document.body.dir == "ltr") {
var datePattern;
if (format.formatLength == "full") {
datePattern = "EEEE d MMMM y";
}
else if (format.formatLength == "long") {
datePattern = "d MMMM y";
}
else if (format.formatLength == "medium") {
datePattern = "dd/MM/yyyy";
}
else { // short format or unspecified
datePattern = "d/M/yyyy";
}
format.datePattern = datePattern;
}
return locale.format(date, format);
},
/**
* get the date string based on date/time selector (default is both date and time)
* convenience function for other widgets with fullYear to true and formatLength
of short
* @private
* @param selector (string, optional)
*
can have value of either "date", "time" or "timestamp" (default)
* @return the text for displaying the date
*/
getLocaleDate: function(date, selector) {
var format = {selector: selector, fullYear: true, formatLength: "short"};
var formatLength = ecm.model.desktop.valueFormatter.formatLength;
if(formatLength) {
format.formatLength = formatLength;
}
return this.formatLocaleDate(date, format);
},
ICN Plugin Mechanism of Displaying Date/Time in Long
Format
ICN is extensible using software modules created by third parties, called plug-ins. A plugin implements one or more of a group of extension interfaces defined for the application.
These implementations then extend the system in some fashion according to the writer of
the plug-in.
ICN plug-ins are quite powerful in that they allow extension of the browser and services
layers in a single plug-in. They also allow the configuration interface to be extended with
plug-in specific configuration.
An ICN Plugin can be developed using RAD, Rational Application Developer. Here are
the component files of the plugin.
The ICN plugin extends the browser layer and redefines the ValueFormatter javascript
class.
longDatePluginDojo/ValueFormatter.js
formatValue: function(value, type, format) {
......
} else if (type == "xs:date") {
if (!value || value == "") {
formattedValue = ""; // explicit check for no date value
} else {
var date = stamp.fromISOString(value);
if (date == null) {
return ecm.messages.error;
}
if (this.locale == "ar" && document.body.dir == "ltr") {
format = "d/M/yyyy";
}
if (format) {
formattedValue = locale.format(date, {
locale: this.locale,
selector: "date",
datePattern: format
});
} else {
formattedValue = locale.format(date, {
locale: this.locale,
selector: "date",
formatLength: "long",
fullYear: true
});
}
}
} else if (type == "xs:time") {
if (!value || value == "") {
formattedValue = ""; // explicit check for no time value
} else {
var date = stamp.fromISOString(value);
if (format) {
formattedValue = locale.format(date, {
locale: this.locale,
selector: "time",
timePattern: format
});
} else {
formattedValue = locale.format(date, {
locale: this.locale,
selector: "time",
formatLength: "long"
});
}
}
} else if (type == "xs:timestamp") {
if (!value || value == "") {
formattedValue = ""; // explicit check for no datetime value
} else {
var date = stamp.fromISOString(value);
if (this.locale == "ar" && document.body.dir == "ltr") {
format = "d/M/yyyy h:mm a";
}
if (format) {
formattedValue = locale.format(date, {
locale: this.locale,
selector: "date",
datePattern: format
});
} else {
formattedValue = locale.format(date, {
locale: this.locale,
formatLength: "long",
fullYear: true
});
}
}
After the new ValueFormatter is defined, it needs to be activated and taken into effect.
The activation is done by the following code in the plugin.js:
Desktop.valueFormatter = new ValueFormatter();
Extending the Custom Plugin to support long date format
in ICM
The ICN plugin works in ICM 5.2 for Inbaskets, Case List widget, but does not work in
CHV, Case Info, Case History, where ICM uses its own date ValueFormatter, with short
date format.
It is possible to update ICM code to utilize ICN valueFormatter to display dates in ICM.
This would also work for Case Tasks tab, and for Custom Task Search. However this
would require changes to ICM code, and would result in requiring a new release of ICM.
The solution we chose is to provide the feature by extending the ICN plugin. The ICN
plugin modifies the ICN method of displaying date. We also need to adapt the plugin to
handle the date display in ICM.
Our approach is to augment the custom plugin, and update the ICM date function at
runtime. So this will essentially overwrite the existing logic in ICM and replace it with a
new modified function.
The update of the logic needs to be performed after the corresponding ICM code loads. It
can be executed at other times, but the best time is after the user logs in to ICM/ICN. The
ICN Desktop model provides an “onLogin” event, which is triggered after the login
process completes. By connecting to this event method, we can add our ICM event
handler function at the appropriate time. In the handler function, we update the ICM logic
for getLocaleDate, and set its formatLength explicitly to “long”, in order to
display dates in long format in ICM widgets.
require(["dojo/_base/declare",
"dojo/_base/connect",
"dojo/_base/lang",
"ecm/model/Desktop",
"icm/util/Util",
"pvr/widget/editors/StaticTextEditor",
"longDatePluginDojo/ValueFormatter"],
function(declare, connect, lang, Desktop, Util, StaticTextEditor,
ValueFormatter) {
if (Desktop.id == "admin" || !(window.icm && icm.util)) {
// plugin in effect only for non-admin desktops, and when icm.util is
loaded
return;
}
Desktop.valueFormatter = new ValueFormatter();
connect.connect(ecm.model.desktop, "onLogin", function() {
console.log("updating ICM API onLogin");
Util.getLocaleDate = function(date, selector) {
var format = {selector: selector, fullYear: true, formatLength:
"long"};
return this.formatLocaleDate(date, format);
}
var originalFunc = StaticTextEditor.prototype.formatValue;
lang.extend(StaticTextEditor, {
formatValue: function() {
var controller = this.controller || this.property.controller;
var oldSetting = controller && controller.get("formatLength");
if (controller && !oldSetting) {
controller.set("formatLength", "long");
}
lang.hitch(this, originalFunc)();
if (!oldSetting) {
controller.set("formatLength", oldSetting);
}
}
});
});
});
We now have a clean separation of ICN logic and ICM logic in the plugin, and only the
public ICM API is modified or extended.
Supporting Long Date format in ICM Property Widget
The Case Summary widget contains a property widget that displays date fields. The
adaptation for Case Summary is made in LongDatePlugin.js for StaticTextEditor of pvr.
The dojo extend function updates or changes the existing prototype function of a
javascript object. Here we only update one function of the StaticTextEditor class,
namely formatValue. This function is called by _setValueAttr function of the
widget to return the formatted value of a field.
For the date fields in property widget, the above code first saves the existing value of
“formatLength” setting, format the datetime field using long format, then restores the
original value of “formatLength”. This way it does not change the
“formatLength” setting globally, and would not have an adverse effect on other
property fields which could be on different widgets in the same page.
The modification of the logic for property widget will take effect on the following fields in
Case Summary widget in ICM.
• Modified On
• Added On
• Other date fields, such as Due Date.
The first two are system date fields. The third kind covers the user-defined date fields.
Usage of the Plugin
To use the plugin, install the plugin jar file from the ICN admin desktop or in the admin
view. There are no configurations needed for the plugin.
After installing the plugin, refresh the ICM page to see dates in long format.
Discussions
It is better to update the logic in onLogin event, than when the plugin code is loaded. The
reason is the plugin code may be loaded at a different time from when the ICM logic is
loaded. If we were to update the ICM logic when the plugin loads, then we would be
assuming that ICM plugin will load first, then our custom plugin loads. This may
introduce an issue related with timing, and can be unreliable. There is no guarantee that
one plugin may finish loading before another plugin. However, there is guarantee that
when user logs in, the ICM plugin has already been loaded and executed, and the
corresponding ICM objects have been created.
The ICM override is performed when user logs in to ICM/ICN. This is one of the proper
ways to extend ICN/ICM. The override is added as a hook to the ICN onLogin event.
All plugins will be loaded prior to user login. The “onLogin” event is triggered even if
user just refreshes the URL. This mechanism was used in the Sametime plugin to read the
Sametime configuration settings.
The logic update in the plugin does not affect the CHV widget, because the CHV widget
does not use the getLocaleDate function to display date and time. For CHV, we will
continue to use the existing ICM mechanism for displaying dates in medium format.
The long format also displays the time zone information fully spelled out, customers may
just want to show the month spelled out, and may or may not want to display the time
zone info. One proposed approach is to have mechanism in ICN admin desktop to specify
which fields to display.
Conclusion
Extending or overwriting an existing API is a common practice in javascript-based web
applications. It is a recommended approach for enhancement of a released ICN/ICM
product.
With the custom plugin, when ICN shows a date field, such as in a grid, ICN now use the
extended API in the plugin to show dates in ICN widgets. When ICM shows a date field, it
will call the updated/overridden ICM API.
We discussed a custom plugin that shows long date format in ICM client. It works for ICN
widgets as well as ICM widgets, with the exception of CHV widget, which requires its
own specific format.
The LongDate plugin is further adapted to accommodate for Case Summary widget. It
also shows long date format for Modified-on and Added-on fields as well, along with
fields in other widgets, such as Case History and Case Toolbar. And the plugin works on
top of ICM 5.2.1, without code modification to ICM base code.