Sync Time (Core Services)

A sync time is an absolute date and time from which to calculate an even set of intervals in a periodic operation. This is useful to establish precise data points, which would otherwise move with every update if the start and end times are relative times. For example, with a start time of "-12h", an end time of "", and an interval of "1h", a query would evaluate the current time and return 12 values over the last 12 hours. When repeated, the same query would return a different current time and the pattern of timestamps would not match those returned from the first query. However, when a sync time is specified, the same pattern of timestamps would be repeated.

Boundary Types

Sync time supports Inside and Outside boundary types. Boundary types define the behavior of data retrieval at the end points of a specified time range.

PI Web API returns at most two additional values: one before the specified start time, and one after the specified end time. These values are only returned if the sync time shifts the interval such that it no longer aligns with the supplied start or end time.

Time Zones

Sync time, start time, end time, and action can all include time zone information. PI Web API resolves multiple specified time zones in the following order:

  1. If the sync time string representation includes a time zone, it is used.

  2. If the action specifies a time zone (such as through the timezone query parameter), it is used.

  3. If no time zone is specified, the PI Web API server time zone is used as a fallback. Note that this fallback is especially important for time zones that are offset by non-hour intervals (for example, India Standard Time, which is UTC+05:30). If a sync time is specified without an explicit time zone, the periodic operation is translated by this additional offset.

Sync Time Examples

In PI Web API, a periodic operation entails taking some action (retrieving data, performing a computation, and so on) at evenly-spaced intervals. To demonstrate these concepts, look at the Stream controller's Interpolated endpoint using the following values:

No sync time

When no sync time is specified, the operation works as usual. This means that the result has the timestamps { "2014-01-01T01:00:00Z", "2014-01-01T02:00:00Z", ..., "2014-01-01T22:00:00Z" }.

Sync time is "1985-08-21T00:30:00Z", and boundary type is "Inside"

With this sync time and boundary type, the result has the timestamps { "2014-01-01T01:30:00Z", "2014-01-01T02:30:00Z", ..., "2014-01-01T21:30:00Z" }. Notice that, even though the start time was 1:00AM, the first value is at 1:30AM. This is because the "Inside" boundary type retains the results (the range) inside the start and end time (the domain).

Sync time is "1985-08-21T00:30:00Z", and boundary type is "Outside"

With this sync time and boundary type, the result has the timestamps { "2014-01-01T00:30:00Z", "2014-01-01T01:30:00Z", ..., "2014-01-01T21:30:00Z", "2014-01-01T22:30:00Z" }. Notice that the first and last values are outside the start and end time (the domain).

Enabling Operational Intelligence