Background

Anyone who has tried to format or manipulate dates using base JavaScript can likely relate to my feelings of frustration. If I want to do something as simple as setting a variable to one month from today, I need a big ugly mess that looks something like this:

var nextMonth = new Date();
var nextMonth.setMonth(nextMonth.getMonth() + 1);

Even then, I can never remember if that will work properly when I'm going from December to January or going from the 31st of the month to a month with less than 31 days. It gets worse when the required changes are more complex.

Fortunately, there are solutions to this problem. My favorite JavaScript date library is Moment.js. It provides a multitude of date formats and significantly simplifies date manipulation. Using Moment.js, the above example would look like this:

var nextMonth = moment().add(1,"month").toDate();

(Depending on the use case you might not even need the "toDate()" part.)

So, how does this apply to IBM BPM? It's a bit confusing, but I'll try to break it down into all of the different scenarios.

Using Moment.js in IBM BPM Coach Views

One good place to use Moment.js is inside of coach views.

Adding Moment.js with Brazos UI

If you are using the Brazos UI toolkit, Moment.js is already included, and it's used in many of the different Brazos UI controls already. To use Moment.js in your own coach view, simply add Moment.js as an AMD dependency and reference the library as normal.

Module ID: moment-with-locales/moment-with-locales
Alias: moment

Adding Moment.js without Brazos UI

If you're not using Brazos UI, you'll need to add Moment.js to your project. Download Moment.js (we recommend moment-with-locales.js), and add it to a zip file by itself (this is necessary for adding an AMD dependency in IBM BPM) called moment-with-locales.zip. Now add that file to your IBM BPM process app (or toolkit) as a Web File.

Next, you'll need to create a package map file so that your coach view knows where to find the zip file. It should be named something like packagemap.js and look something like this:

require({
 packages: [
 {
   name: 'moment-with-locales',
   location: com_ibm_bpm_coach.getManagedAssetUrl('moment-with-locales.zip',
 com_ibm_bpm_coach.assetType_WEB, 'MOMENT')
 }
 ]
});

Note: In this example, my process app's acronym is "MOMENT". You should replace that value with your process app (or toolkit) acronym.

Now in your coach view you can simply include packagemap.js as an Included Script, and add the AMD dependency.

Verify that Moment.js has been included properly

To verify that you've added your AMD dependency properly, you can add this line of code to the load event handler:

console.log("moment:",moment().format());

If everything works properly, you should see something like this in your browser's JavaScript console when running your coach:

moment: 2019-03-06T14:03:25-08:00

Using Moment.js Inside of Coach Views

Now that you've added Moment.js to your coach view, you can reference the moment library in any of your coach view's event handlers.

Now you can do something useful with moment. Here's a simple example. I created a coach view that's bound to a date object, and I added the following code to the load event handler:

var node = document.createTextNode("One month from now is "+ moment(this.getData()).add(1,"month").format("M/D/YYYY"));
this.context.element.appendChild(node);

The result is the following:

Using Moment.js in IBM BPM Service Flows or Server Scripts

Using Moment.js inside coach views is great, but a lot of variable manipulation happens in Service Flows and Server Scripts. Fortunately, you can use Moment.js in these places as well.

Adding Moment.js to your process app or toolkit

In order to access Moment.js in code that runs server side, you'll need to add Moment.js as a server file. This is as simple as taking the raw moment-with-locales.js file and adding it to your process app (or toolkit) as a Server File.

Using Moment.js in server side code

Now you can freely use Moment.js in your server side code. There are some quirks though.

Converting an IBM BPM Date (TWDate) to a Moment object

If you want to manipulate an IBM BPM date object, you'll first need to convert it to a Moment object. Moment.js makes it easy to convert a JavaScript date object to a Moment object, but IBM BPM doesn't use standard JavaScript dates. In order to use moment, you'll first need to convert your IBM BPM date object to a standard JavaScript date object using the toNativeDate() method.

var myMoment = moment(tw.local.myDate.toNativeDate());

Converting a Moment object to an IBM BPM Date

Conversely, IBM BPM makes it easy to initialize an IBM BPM date from a standard JavaScript date object. But again, Moment.js doesn't produce standard JavaScript date objects by default. In order to set an IBM BPM date from a Moment object, you'll need to use the toDate() method from Moment.js.

tw.local.myDate = moment().toDate();

Manipulating an IBM BPM Date using Moment.js

So if we put it all together, we'll need to use both of these approaches when manipulating dates. If we want to add a month to a date, it will look like this:

tw.local.myDate = moment(tw.local.myDate.toNativeDate()).add(1,"month").toDate();

Limitations

Unfortunately, this approach is not currently possible inside of Client-Side Human Service scripts. The best option if you're using a Client-Side Human Service is to call a Service Flow for your date manipulation. While this can be inconvenient, it's a good practice anyway.

Note: if I'm wrong about this, limitation, I'd love to know!

Wrap Up

That's it! I hope this helps make IBM BPM dates a little less frustrating for you. Please reach out if you have any questions.