ProcessValues

Description

Retrieves a set of process value records (where each record includes value + time + quality, or VTQ) for the specified tags.

URL

/ProcessValues

Method

GET 

Required Parameters

• FQN=[string ]
  The fully qualified name for the tag. A fully qualified name uses the format: datasource.tagname.

• StartDateTime=[DateTimeOffset]
  The starting date and time. This is always specified in UTC using the RFC3339 / ISO8601 format with the Z time zone designator. For example: 1985-04-12T23:20:50.52435Z

• EndDateTime=[DateTimeOffset]
  The ending date and time. This is always specified in UTC using the RFC3339 / ISO8601 format with the Z time zone designator. For example: 1985-04-12T23:20:50.52435Z

Optional Parameters

• OPCQuality=[Int32]
  The data quality as reported by the source.

• Value=[Double]
  0 or 1.

• Bounding=[true]
  If the query specifies a start point, this parameter shows the first data point that occurs on or before the query start. If the query specifies an end point, this parameter shows the first data point that occurs on or after the query end. The actual date and time of the start/end point are shown, even if it's outside the bounds of the query.

• Text=[String]
  For string tags, contain the value.

  For discrete tags, contains the message associated the value (0 or 1).

• TagFilter=[String]
  Allows you to use a query string using OData filter query notation to filter results by tag attributes. Supported tag attributes include FQN, description.

  TagFilter can include up to 20 AND clauses, or up to 20 OR clauses. You cannot mix AND and OR in the same query.

  Operators should be lowercase, and searches are case-insensitive.

  Valid Format:

  Historian/v2/ProcessValues?TagFilter=startswith(Source,'MVDS') and TagType eq 'string'

  Invalid Format:

  Historian/v2/ProcessValues?TagFilter=startswith(Source,'MVDS') And TagType eq 'string'

• Expression=[String]
  For analog tags, you can perform UOM conversion on retrieved tag data by including a string expression in the following format:

  UOM([tag FQN 1],[engineering unit name 1];[tag FQN 2],[engineering unit name 2];...)

  You can provide one or more pairs of tag names and engineering unit names, and during retrieval the data will be converted to the specified units, if valid. If the unit conversion is not valid, the tag's base unit is used instead.

  Note: This feature requires special licensing. If a license is not available and the "Expression" parameter is used, no data is retrieved and an error message is displayed.

Success Response

Code: 200 
Content: { fqn: plant12.pump6, datetime: 2016-09-03T18:44:09.352247Z}

Error Response

Code: 404 NOT FOUND 
Content: { error : "FQN doesn't exist" }

or

Code: 401 UNAUTHORIZED 
Content: { error : "You are unauthorized to make this request." }

Sample Query

Scenario 1

This query returns process values for a specific tag identified by its fully qualified name (datasource.tagname). Using a "$filter" clause, it specifies a tag named tank_level within the Baytown data source. The result is a list of values for the tank_level tag.

http://localhost:32569/Historian/v2/ProcessValues?$filter=FQN+eq+'Baytown.tank_level'

Scenario 2

This query includes a start date time, end date time, and other query parameters.

http://localhost:32569/Historian/v2/ProcessValues?$filter=FQN+eq+'Baytown.tank_level'+and+DateTime+ge+2014-07-04T23:57:29Z+and+DateTime+le+2014-07-05T00:02:29Z&RetrievalMode=BestFit&Resolution=6500

Sample Query

Scenario 3

This query returns the current day of the month, and uses the Expression parameter to retrieve the value in hours.

http://localhost:32569/Historian/v2/ProcessValues?$filter=FQN+eq+'SysDateDay'&Expression=UOM([SysDateDay],[Hour])

Sample Output

{

"odata.metadata": "http://localhost:32569/Historian/v2/$metadata#ProcessValues",

"value": [

{

"FQN": "SysDateDay",

"DateTime": "2020-10-29T16:57:29.0128451Z",

"OpcQuality": 192,

"Value": 696.0,

"Text": "696",

"Unit": "Hour"

}

]

}

Sample Query

Scenario 4

This query returns process values for a list of tags with fully qualified names (FQN) beginning with "sys", with values falling within a specific date range. If you don't know the fully qualified name of a specific tag, you can use the TagFilter parameter to get a list of possible matches.

http://localhost:32569/Historian/v2/ProcessValues?$filter=DateTime+ge+2019-01-15T03:57:29Z+and+DateTime+le+2021-01-17T03:50:54.881Z&TagFilter=startswith(FQN,'sys')

Sample Output

{

"@odata.context": "http://localhost:32569/Historian/v2/$metadata#ProcessValues",

"value": [

{

"FQN": "SysClassicDataRedirector",

"DateTime": "2019-01-15T03:57:29Z",

"OpcQuality": 0,

"Value": null,

"Text": null,

"Unit": ""

},

{

"FQN": "SysClientAccessPoint",

"DateTime": "2019-01-15T03:57:29Z",

"OpcQuality": 0,

"Value": null,

"Text": null,

"Unit": ""

},

{

"FQN": "SysConfigStatus",

"DateTime": "2019-01-15T03:57:29Z",

"OpcQuality": 0,

"Value": null,

"Text": null,

"Unit": "units"

}

]

}

Sample Query

Scenario 5

This query returns process values for a list of tags whose FQN ends with "sec", with values falling within a specific date range.

http://localhost:32569/Historian/v2/ProcessValues?$filter=DateTime+ge+2019-01-15T03:57:29Z+and+DateTime+le+2021-01-17T03:50:54.881Z&TagFilter=endswith(FQN,'sec')

Sample Output

{

"@odata.context": "http://localhost:32569/Historian/v2/$metadata#ProcessValues",

"value": [

{

"FQN": "SysDataAcqOverallItemsPerSec",

"DateTime": "2019-01-15T03:57:29Z",

"OpcQuality": 0,

"Value": null,

"Text": null,

"Unit": "units/s"

},

{

"FQN": "SysStatusRxEventsPerSec",

"DateTime": "2019-01-15T03:57:29Z",

"OpcQuality": 0,

"Value": null,

"Text": null,

"Unit": "units/s"

}

]

}

Sample Query

Scenario 6

This query returns process values for a list of tags whose FQN contains "timesec", with values falling within a specific date range.

http://localhost:32569/Historian/v2/ProcessValues?$filter=DateTime+ge+2019-01-15T03:57:29Z+and+DateTime+le+2021-01-17T03:50:54.881Z&TagFilter=contains(FQN,'timesec')

Sample Output

{

"@odata.context": "http://localhost:32569/Historian/v2/$metadata#ProcessValues",

"value": [

{

"FQN": "SysTimeSec",

"DateTime": "2019-01-15T03:57:29Z",

"OpcQuality": 0,

"Value": null,

"Text": null,

"Unit": "Second"

}

]

}

Sample Query

Scenario 7

This query returns process values for a list of tags whose description contains "timesec", with values falling within a specific date range.

https://localhost:32569/Historian/v2/ProcessValues?$filter=DateTime+ge+2019-01-15T03:57:29Z+and+DateTime+le+2021-01-17T03:50:54.881Z&TagFilter=Contains(Description,'timesec')

Sample Output

{

"@odata.context": "http://localhost:32569/Historian/v2/$metadata#ProcessValues",

"value": [

{

"FQN": "SysTimeSec",

"DateTime": "2019-01-15T03:57:29Z",

"OpcQuality": 0,

"Value": null,

"Text": null,

"Unit": "Second"

}

]

}

Similar to the previous examples, you can search for tags with descriptions that start with, end with, or contain specific text.