Using Startbound and Endbound Retrieval Modes

Startbound

The Startbound retrieval mode is used to obtain the last-known value of a given tag before the date and time specified in the request.

The return will include the last updated VTQ record occurring before the EndDateTime. In the following POST body example, an EndDateTime of 00:11 is provided with a Startbound retrieval mode. The return will be the record at the 00:08 timestamp ["00:08", "10"] because there was no record at 00:10.

{

"FQN": ["MyTag1"],

"RetrievalMode": "Startbound",

"EndDateTime": "00:11"

}

Note the following when using the Startbound retrieval mode:

• If you only specify an FQN and Startbound retrieval mode without EndDateTime, then the time at execution of the request will be used as the EndDateTime.

• If you specify an EndDateTime that is exactly equivalent to the VTQ, that VTQ will be returned. From the above example, if the EndDateTime is set to 00:06, the timestamp and value returned will be [“00:06”, “7”].

• If the provided EndDateTime occurs before the first VTQ for the specified tag (i.e., “00:01”), an empty array will be returned.

• If specifying Startbound with a GET request, you will not be able to use EndDateTime. Instead, use DateTime le (less than or equal to), or DateTime lt (less than). This will result in the return of the last-updated value with a timestamp less than the DateTime specified.

Endbound

The Endbound retrieval mode is used to obtain the first-known value of a given tag after the date and time specified in the request.

The return will include the last updated VTQ record occurring after the StartDateTime. In the following example, a StartDateTime of 00:07 is provided with an EndBound retrieval mode. The return will be the record at the 00:08 timestamp ["00:08", "10"].

{

"FQN": ["MyTag1"],

"RetrievalMode": "Endbound",

"StartDateTime": "00:07"

}

Note the following when using the Endbound retrieval mode:

• If you only specify an FQN and Endbound retrieval mode without StartDateTime, then the time at execution of the request will be used as the StartDateTime. This will result in an empty array.

• If you specify a StartDateTime that is exactly equivalent to the VTQ, that VTQ will be returned. From the above example, if the StartDateTime is set to 00:06, the timestamp and value returned will be [“00:06”, “7”].

• If the provided StartDateTime occurs before the first VTQ for the specified tag (i.e., “00:01”), the first value (i.e., “4”) will be returned.

• If specifying Endbound with a GET request, you will not be able to use EndDateTime. Instead, use DateTime ge (greater than or equal to), or DateTime gt (greater than). This will result in the return of the last-updated value with a timestamp greater than the DateTime specified.

ProcessValues retrieval for versioned data sets

In specific use cases, Historian may store multiple records for a given tag recorded with the same timestamp. When this occurs, at least one record is stored as a "versioned-original."

In specific situations, Historian can sometimes record multiple records labeled as "versioned-original" with the same timestamp. In the example below, values of 7, 8, and 2 are recorded at 00:06.

In this scenario, any of those values may be returned with a Startbound or Endbound request to ProcessValues.

In the event that two records exist at the same timestamp, where one is "versioned-original" and the other "versioned-latest," Historian Client Web will return the value associated with "versioned-latest" by default. From the example POST body below, the returned value would be 8.

{

"FQN": ["MyTag1"],

"RetrievalMode": "Startbound",

"EndDateTime": "00:07",

"Version": "Latest"

}

In order to toggle between the two records, you must specify "Version": "Latest" or "Version": "Original" in your query.

Filtering returns by quality

Records can be filtered for OPC quality so that "bad" records are not returned. To filter for quality, append your query with “QualityRule”: “Optimistic”, as shown below:

{

"FQN": ["MyTag1"],

"RetrievalMode": "Startbound",

"EndDateTime": "00:07",

"QualityRule": "Optimistic"

}

“QualityRule”: “Optimistic” configures the query to return only records with an OPC Quality of “uncertain” (quality 64) or “good” (quality 192). In the example below, including “QualityRule”: “Optimistic” means that -1 at 00:06 is returned.

In this second example below, the record at 00:06 with an OPC quality of 0 is not returned. Instead, the value of 7 at 00:04 is returned.