Technical Blog Post
Specifying a time range for DASH charts
Dashboard authors often like to chart data over a time range, something like "the past 8 hours." The charting widgets included with versions of IBM's Dashboard Application Services Hub before 3.1.1 (as bundled with Jazz for Service Management 1.1.1) appeared to make this easy. When a data set included a parameter of the data type datetime or isodatetime, the chart's configuration user interface generated a popup dialog that let the user enter the time range.
This was a feature added in response to a need by a customer for a particular Tivoli product. Even though the charting widgets presented this dialog for any data set with a time parameter, there are only a couple data providers that could cope with its output. Others would simply fail. For this reason the new charting widget did not follow suit.
The correct parameter data type for specifying a time range is isointerval, which the new charting widgets do support. Though few data providers currently support it, the need has been communicated to the product teams, and where time ranges are appropriate, the parameter is being added (APM, for example, will include isointerval parameters for historical datasets in their upcoming release).
While the new charting widgets support isointerval, they do not include the nice dialog for user input, but instead present a simple textbox. We can specify a time range, but it needs to be in a specific format.In an better world, you could open a dialog like the one above, and you will sometime soon, but for now you have to know what to type, and that's the purpose of this article.
Date-times, time ranges and durations are specified per the ISO 8601 specification.
A duration is represented as PnYnMnDTnHnMnS, or n Years, n Months n Days, T introduces time, n Hours, n Minutes, n Seconds.
A date-time is represented as YYYY-MM-DDThh:mm:ss.sssTZ where TZ is simply Z for UTC, or an offset like -0500 for the minus 5 hours of EST.
An interval is represented as start date-time/end date-time
An interval also may be represented as just a duration in which case it's up to the data provider to specify how it's interpreted. (In the case of APM historical data, it is real-time minus the given duration.)
The ISO 8601 spec also permits, start date-time/duration and duration/end date-time, but they are not currently supported.
Sidebar: The legacy charting widget used a minus sign in front of the duration to indicate real time minus the duration. That usage is non-standard and has its use is discouraged.
Now we know, as input for an isointerval type dataset parameter, the user would type in will be something like this:
- Real Time: enter no value. By not specifying an interval, you are saying you want current data.
- Real time minus some interval: For the last 12 hours, it's P0Y0M0DT12H0M0S, or the shorthand version PT12H. Some experimentation will be required to determine how terse you can abbreviate a duration.
- An absolute interval: From 2-4AM April 6th EDT, it's 2015-04-06T02:00:00-0400/2015-04-06T04:00:00-0400. In my tests, providers correctly accept date-times including the timezone, but the timezone of returned data is a function of the data provider.
The dashes separating the date part and the colons separating the time parts are optional per the spec, but are typically included, (The legacy chart omitted them, which was probably an agreement with ITM and/or APM. The history has been lost.) If the provider accepts the punctuation, I would suggest including it, as the string is easier to read.
For more detail on the ISO 8601 date-time, interval and duration format, the ISO 8601 Wikipedia article offers a clear description.