Using the Time Tokens in IDM 3.5


Identity Manager 3.5 added a bunch of new features, big and small. Some are important new constructs, such as the Library object for reusing code, or new support for the ECMA Script. Others are much more subtle, such as the new Time and Convert Time tokens.

In the argument builder, whenever you need to build a text string, you will find two new tokens:

  • Time - gets the current time (as of the event) and report it in a very specific format
  • Convert Time - takes a time value in one format and convert to a second format

This is basically a GUI wrapping the Java time functions, but what a GUI it is!

Now for some examples ...


Click to view
Figure 1 - Simple Time

Suppose you need to get the current time at the event - you would use the Time token. The control in the Format string is where the magic of this comes into play. The language and Time Zone support are great - and pretty obvious, even if they support seemingly every language and time zone ever, and multiple times!

Click to view
Figure 2 - "Silly" time example

That is a silly example of setting the timezone to something I have never heard of, and a language I cannot read, being an ignorant North American who never travels.

Click to view
Figure 3 - Time example with MMM

This one uses MMM to represent Aug, Sep, Oct, and so on, separating the values between - for no good reason other than because I can. Then comes the 2-digit day of the month, then the 4-digit year (I guess that will suffer the Y10K problem in 7993 years from now - I recommend starting to plan soon!), then the 2-digit hour, colon, 2-digit minutes, colon, 2-digit seconds, then 2-digit milliseconds.

<token-time format="MMM &lt-> dd &lt->yyyy hh:mm:ssSS " tz="EST"/>

Note the "&lt" replacing instances of the less than sign ("<"), which is how Designer escapes "less than" signs embedded in XML.

What is nice is that once you get a feel for it, you can tweak it easily in XML or in the Designer UI.

This is a pretty silly example, but the intent is to show that whatever foolish format you are required to handle, you should be able to. If you cannot do it within the Time or Convert Time token, you can always use combinations of the other tokens (nouns and verbs) to modify the output of Time.

Options and Buttons

The way Designer pops up the option menus makes it hard to show the variety of options in all of the various fields, but there are many.

I recommend that if you are not using Designer, to go get it. If you are, you should create a test Project for storing your personal hints, tips, and code snippets. Make a vault that does not actually point at any servers, (i.e., completely offline model) and add a driverset, and import any driver (loopback may be the simplest for this example).

Then start using that to look at XML snippets you get from the Time token, such as the one shown above, and you will get a good feel for how to control some of the fields.

One really smart feature they added was the Test button. The Time token has one, which takes the current system time value, runs it through the format string and shows you what it generates. The Convert Time token has two: one for Source, and one for Destination. This is a huge time saver, as opposed to having to iterate through a test with a real object or even with Simulator. Just click Test - and save all that time and effort.

Note: Other tokens could learn from this UI! I understand it is hard when the sample data is not at hand, and that is what Simulator is for. But a limited Simulator run on say ParseDN, where you give it or pick a DN and change the parameters and keep
clicking Test to see if it does what you want, would be a huge time saver when debugging!

Click to view
Figure 4 - Convert Time example

The Convert Time token is even smarter, since it has TWO test buttons: one for the input format and one for the output. (If you are looking for it, Time is a noun, Convert Time is a verb - so Time is in the top right half of the selector, and Convert Time is in the middle-right list in string builder).

Next to each Format line (there are two Format lines in the Convert Time token: one for source, and one for destination) are two buttons. I am not sure what their exact names are, but they provide some sample patterns beyond the samples the Format dropdown itself provides. Another nice UI touch is that each possible time field is represented
in those two buttons.

I was sure I had read a blog or forum post talking about this token once that said if there was anything missing to let the author know, but I cannot find it now. I am curious if anyone has a case that the token cannot handle! There must be some, but boy it is probably contrived!

Test Button Feature

The test button feature shown in the screen shots appears to only be available in the Designer 3 series. This is NOT a stable or supported release yet; the latest supported release is in the 2.x series. Version 2.01 is the latest released version as I write this (9/18/07), with 3.0 M1, and 2.1 RC1 being the stable versions.

3.0M1 is mostly OK, and it is a great improvement over the 2.x family. There are a number of UI improvements that will make your day-to-day life in IDM easier, but there are definite bugs still in there.

So if you were reading this article and trying to find the Test button, check your Designer version to see which you are running. I had been running 3.0 M1 for so long, I never even noticed that it was
missing in the 2.x family until now.

The functionality of building and decoding date formats looks like it is all there in the Designer 2.x family, the only difference I have seen so far is the Test buttons.

As an update this functionality has persisted into the IDM 4.x family line as well.



How To-Best Practice
Comment List