Time Handling
optile's OPX Analytics provides a simple and powerful tool for you to creat meaningful charts and to present your required response data, with your specified time periods.
Selected Period
A KPI value always refers to a time period, the Selected Period. It is given in the query request by specifying these values:
- Period end: A timestamp with the attribute name
periodEnd
. It is actually the first moment outside of the time period; i.e., it is no longer part of the Selected Period. If no period end is specified, OPX will assume it is now (more implications on this below). - Period length: This is defined by two attributes:
-
sliceUnit
: The unit of the time slice; e.g., hour, day, week, month. -
sliceUnitCount
: The number of units that make up the actual time slice.
Typically, your Selected Period will be a time slice with a length of one day, or one week, etc. However, you can also specify 12 hours, or two weeks, for example.
If no periodEnd
is given, OPX assumes that the client wants data about the immediate past, e.g., the last 24 hours or the last week, as specified by the period length. This is referred to as a Rolling Period. No rounding takes place, so requesting one day back at 10:51 from today will return the KPI value aggregation between 10:51 yesterday (inclusive) and 10:51 today (exclusive). Also the natural equivalencies always apply; i.e.,: 24 hours = 1 day, 1 week = 7 days, 1 quarter = 3 months, 1 year = 12 months.
If an explicit periodEnd
in the past is specified, we call it a Calendar Period. In the typical case there will be sliceUnitCount = 1
. OPX then assumes the client wants to see a natural calendar unit; e.g., one day from midnight to midnight. Therefore, it will round the requested periodEnd
to the natural end of the sliceUnit
in the calendar to form the Selected Period (midnight in that example).
If, however, sliceUnitCount
is greater than 1 (e.g., for 12 hours) there will be no rounding. So 12 hours back from 16:23 will aggregate the KPI value from 4:23 on.
If the periodEnd
is in the future the query will return the value as accumulated until now, possibly 0.
Time Period: Drill-Up and Drill-Down
For data analysis, it is often useful to compare a KPI value from the Selected Period with values from different time periods. OPX offers drill-up or drill-down functionalities in relation to the selected period. For instance, assume that the selected period is one day. The OPX can provide KPI values for the entire week that contains this day, a drill-up operation, or provide KPI values of 24 hours that are contained within this day (i.e., drill-down). You can think of this as zooming-in or zooming-out from a digital image. Depending on the resolution of the data you are interested in, the OPX will either give you a finer or coarser view of the data.
Drill-Up Period
This period is used to set the selected period into context of preceding and subsequent time slices. Those time slices will all have the same length and together make up the Drill-Up Period. The selected period is one of those slices within the Drill-Up Period.
Returning data about the Drill-Up Period can be requested in the call for KPI details. The extent is always calculated by OPX, not defined by the client. OPX will take the given selected period and move up by one or two calendar units. For example, OPX will show a selected day in context of the other days of the week, in order to display a clear and concise graph. See details below.
The extent of the calculated Drill-Up Period will be returned by giving a periodEnd
again and the sliceCount
, which represents the number of time slices within the Drill-Up Period. Do not confuse this with the sliceUnitCount
, which is a factor in specifying the length of each of those slices.
In addition to the KPI value of each time slice in the Drill-Up Period, the detail query will also return the maximum value maxValue
, minimum value minValue
, and average value avgValue
of time slices in this Drill-Up Period. This will allow the user to immediately understand how the performance of the selected period compares to other periods.
Visualization of Drill-Up Period

Looking at a selected period, a user should not only be able to navigate to the time period before or after the selected period, but also make a larger jump by shifting the Drill-Up Period to the next or previous period. However, since the client cannot explicitly specify the Drill-Up Period, the response helps by returning the attributes previousSelectedPeriod
and nextSelectedPeriod
. They represent the selected period that could be used in a subsequent request in order to shift the whole Drill-Up Period back or forth.
Determining the Drill-Up Period from the Selected Period
The Drill-Up Period will always try to represent the selected period in a larger and more meaningful context, keeping the number of data points (time slices) balanced between too little information and an information overload. As a result the client needs very little logic, it should "just" visualize the data to that extent as it is returned.
For Rolling Periods (ending now), OPX will calculate the KPI value by aggragating the data from the given period in the past (constituting the selected period); e.g., the last 24 hours (without any rounding). The corresponsing Drill-Up Period will consist of this selected period plus seven more time slices of equal length in the past.
For Calendar Periods representing typical units (e.g., a day) with sliceUnitCount = 1
OPX will present the selected period in the context of a calendar unit one or two levels higher (e.g., the selected day between the other days of a natural week), again trying to find a balance between too little and too many data points.
Specifically it will use this mapping:
Selected Period Length | Example periodEnd | Resulting Selected Period | Drill-Up Period Unit | Example Drill-Up Period |
1 Hour | 10:00 | 09:00 - 10:00 (exclusive) | Day | 24 slices between 00:00 this day and 00:00 next day (exclusive) |
1 Day | 24/06/2015 00:00 | Tuesday, 23/06/2015 | Week | 7 slices between Monday, 22/06/2015 0:00, and Monday, 29/06/2015 00:00 (exclusive) |
1 Week | 22/06/2015 00:00 | Monday 15/06/2015 to Sunday 21/06/2015 (inclusive) | All weeks that are fully in this quarter ((but not those that reach into another quarter, unless it is the selected week. The selected week is in a quarter if 4 or more days (out of 7) are in that quarter)). | 12 slices between Monday 06/04/2015 and Monday 29/06/2015 (exclusive) |
1 Month | 01/07/2015 00:00 | June 2015 | Year | 12 slices between 01/01/2015 and 01/01/2016 (exclusive) |
1 Quarter | 01/07/2015 00:00 | 2nd quarter of 2015 | 4 quarters before and after | 9 slices between 01/04/2014 and 01/07/2016 (exclusive) |
1 Year | 01/01/2016 | The year 2015 | 4 years before and after | 9 slices between 2011 and 2019 (inclusive) |
If the derived Drill-Up Period should include one or more time slices that would lie entirely in the future, they will naturally be returned as 0 values. The Drill-Up Period will stick to the calendar system, so to say.
In case the selected period is not a typical calendar unit; i.e., sliceUnitCount
is bigger than 1, there will be no rounding for the selected period. Therefore, it could lie on the time line; e.g., 12 hours from 04:23 to 16:23. The Drill-Up Period will respect that and instead of aligning with natural calendar units return 4 time slices before and after the Selected Period, resulting in a total of 9 slices.
If in the case that the derived Drill-Up Period should include one or more time slices that lie entirely in the future, they will not be returned, but instead the same number of time slices in the past will be added.
Example: If you aggregate 3-hourly with a selected period of 12:00h to 15:00h and do a request at 18:30, the response will drop the last 2 time slices and add two from the past instead like this:
Request time: 18:30
Time Slice | 18-21 | 21-24 | 00-03 | 03-06 | 06-09 | 09-12 | 12-15 | 15-18 | 18-21 | 21-24 | 00-03 |
Value | 240 | 120 | 40 | 10 | 40 | 160 | 170 | 320 | 60 (unfinished) | - | - |
Comment | added | added | | | | | Selected Period | | | dropped | dropped |
Drill-Down Period
This period is used to represent the selected period as a sum of smaller time slices. These time slices will all have the same length and together make is what we call a Drill-Down Period.
Returning data about the Drill-Down Period can be requested in the call for KPI details. Its extent is always calculated by OPX, not defined by the client. OPX will take the given selected period and break it down into smaller time units. For example it will show a selected day in context of the individual hours that make up that day.
The extent of the calculated Drill-Down Period will be returned by giving a periodEnd
again, and the sliceCount
which represents the number of time slices within the Drill-Down Period. The sliceUnitCount
is a factor in specifying the length of each of those slices.
In addition to the KPI value of each time slice in the Drill-Down Period, the detail query will also return the maximum value maxValue
, minimum value minValue
, and average value avgValue
of time slices in this Drill-Down Period.
Visualization of Drill-Down Period

In the graph above, the selected period is a single day: Thursday, July 2. The Drill-Down Period for it consists of 24 hours, each represented with its own KPI value. A user can navigate back and forth within these 24 hours, as well as make a larger shift of the Drill-Down Period to the previous or next one. Since the client cannot explicitly specify the Drill-Up Period, the response helps by returning the attributes previousSelectedPeriod
and nextSelectedPeriod
. These attributes denote the previous and the Drill-Down Periods that could be selected from the current Drill-Down Period.
Deriving Drill-Down Period from Selected Period
The Drill-Down Period is designed to break down the selected period into smaller user-intuitive time units. The mapping that is used for it is given below.
Mapping for Calendar Units:
Selected Period Length | Example periodEnd | Resulting Selected Period | Drill-Down Period | Example Drill-Down Period |
1 Day | 24/06/2015 00:00 | Tuesday, 23/06/2015 | 24 hours | 24 slices between 00:00 this day and 00:00 next day (exclusive) |
1 Week | 22/06/2015 00:00 | Monday 15/06/2015 to Sunday 21/06/2015 (inclusive) | 7 days | 7 slices between Monday, 22/06/2015 0:00, and Monday, 29/06/2015 00:00 (exclusive) |
1 Month | 01/07/2015 00:00 | June 2015 | 30 days | 30 slices between Monday 01/06/2015 and Wednesday 01/07/2015 (exclusive) |
1 Quarter | 30/09/2015 00:00 | 3rd quarter of 2015 | All weeks that have 4 or more days within this quarter | 14 slices between 01/07/2015 and 01/10/2016 (exclusive) |
1 Year | 01/01/2016 | The year 2015 | 12 months | 12 slices between 01/01/2015 and 01/01/2016 (exclusive) |
Mapping for Rolling Time Units (assuming current date and time is 08/08/2016, 22:00):
Selected Period Length | Example periodEnd | Resulting Selected Period | Drill-Down Period | Example Drill-Down Period |
24 hours | now | 07/08/2016,00:00 to 08/08/2016, 00:00 (exclusive) | last 24 hours | 24 slices between 07/08/2016, 00:00 and 08/08/2016, 00:00 (exclusive) |
7 days | now | 01/08/2016 to 08/08/2016 (exclusive) | last 7 days | 7 slices between 01/08/2016, 0:00, and 08/08/2016, 00:00 (exclusive) |
30 days | now | 08/07/2016 to 08/08/2016 (exclusive) | last 30 days | 30 slices between 08/07/2016 and 08/07/2015 (exclusive) |
90 days | now | 08/05/2016 to 08/08/2016 (exclusive) | last 90 days | 90 slices between 08/05/2016 and 08/08/2016 (exclusive) |
If the derived Drill-Down Period should include one or more time slices that would lie entirely in the future, they will naturally be returned as 0 values.