OSIsoft: PI Vision I Online Course – Time in PI System
Note: PI Coresight has been renamed to "PI Vision" to better capture the direction of our visualization strategy. PI Vision represents the start of a new path and the next phase of OSIsoft visualization to deliver a unified, powerful, extensible experience.
This document is an excerpt from the Visualizing PI System Data Workbook v2017
You can use a special syntax, called PI time, to specify inputs for timestamps and time intervals in PI client applications, for example PI Vision. PI time uses specific abbreviations and rules in building valid time expressions.
PI Time Expressions
There are two categories of time specification within the PI system:
Fixed Time: An expression that signifies a specific date and time, which will never change.
When to use it: When you want to save a view of your PI System data for a specific time in history.
Example: A user is creating a report that analyzes an equipment failure event which occurred on the 5th of January.
Reference Time: An expression that signifies a date and time relative to the current date and time.
When to use it: When you want to create a dynamic view of your data, which can be used to view data in real-time, or re-used on a periodic basis to create periodic reports.
Example: A user is creating a report that summarizes the weekly production totals. By using relative time expressions, the user will be able to re-use this report every week.
Both Fixed Time and Reference Time can be used with Time Offsets. Time Offsets can also be used alone.
Fixed Time Syntax
A fixed time expression is an expression which includes a date, and optionally a time. If the time is omitted, midnight is assumed
3:00 p.m. on August 23, 2012
00:00:00 (midnight) on September 25, 2012
The PI System can interpret many different formats for fixed time. In the event of an ambiguous input, the Windows Region and Language settings of the computer where the PI Visualization Tool is installed take precedence. For example:.
Region and Language Format
English (United States)
00:00:00 (midnight) on January 5th 2015
00:00:00 (midnight) on May 1st 2015
Reference Time Syntax
A reference-time abbreviation represents a time relative to the current time.
00:00:00 (midnight) of the current day
00:00:00 (midnight) of the previous day
00:00:00 (midnight) on the most recent Friday
00:00:00 (midnight) on the current day in May of the current year
00:00:00 (midnight) on the DDth day of April in the current year
00:00:00 (midnight) on the current day and month in year YYYY
M-D or M/D
00:00:00 (midnight) on the Dth day of month M in the current year
00:00:00 (midnight) on the DDth day of the current month
Use the first three letters as an abbreviation for any day of the week and any month of the year. For example:
00:00:00 (midnight) on the most recent Thursday
00:00:00 (midnight) current day and month in 2015
When specifying PI time, you can use specific abbreviations, listed below, that represent time units. These would be used in constructing Time Offsets.
You can specify the abbreviation, the full time unit or the plural version of the time unit, such as s, second, or seconds. Time offset is any of the time units with a valid value and a + or – sign included, e.g. +8h.
Time offsets could be used alone in a time field or come with a fixed time or reference-time abbreviation.
Time Offset Syntax
Entered alone in a time field, time offsets specify a time relative to an implied reference time. The implied reference time depends on the field where you enter the expression:
- For a start time, the reference time is the current clock time.
- For an end time, the reference time is the start time.
- For a single time stamp, the reference time is the current clock time.
One day before the current clock time (24 hours before the current clock time)
Six hours after the start time
30 minutes before the start time
15 seconds before the current clock time
*Some Rules to Remember
Rule 1: You can only include a single time offset in an expression. Including multiple offsets can lead to unpredictable results. For example, the following time expressions are not valid:
Rule 2: To define a time offset you must include a valid value with any time unit. Only for seconds, minutes or hours, you can specify a fractional value. You cannot specify fractional values for other time units
Rule 3: A fixed timestamp consists of the fields of Year, Month, Day and Time (hours, minutes and seconds). If any of these fields are not specified in the PI time expression, the following values will be assumed by default:
- If Time is not specified, then the default value would be Midnight.
- If Day is not specified, then the default value would be Current Day.
- If Month is not specified, then the default value would be Current Month.
- If Year is not specified, then the default value would be Current Year.