ProcessValues

Description

Retrieves a set of process value records (where each record includes value + time + OPC 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.

• DateTime=[DateTimeOffset ]
  (v2 and later) Specified in UTC using the RFC3339 / ISO8601 format with the Z time zone designator. For example: 2016-09-03T18:44:09.352247Z.

Optional Parameters

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

• Value =[Double ]
  0 or 1.

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

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

• TimeDeadband=[Int]

  The minimum time, in milliseconds, between returned values for a single tag. Applies only to delta retrieval.

• ValueDeadband=[Float]

  The percentage of full scale (range), in engineering units. Any value changes that are less than this percentage are not returned. Applies only to delta retrieval. The default is 0.

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

  "UOM([DataSourceName.TagName],[Name of engineering unit]) as [Custom Tag Alias]"

  You can specify several conversions in a single call as long as each conversion is specified in an individual UOM() function, as shown in the following example:

  "UOM([DataSource.Line3.Units],[Units]) as [Line3Units];UOM([DataSource.Reactor3.Level],[Liters]) as [DataSource.Reactor3.Level];"

  Note the following when using this parameter:

  • If the unit conversion is not valid, the tag's base unit is used instead.

  • If you do not provide an alias, the results of this call will display Expr# for the FQN.

  • If using this parameter, you do not need to specify the FQN array, as tag names will be resolved from the expression. If the expression contains an invalid FQN, the query will fail.

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 produces process values for a list of tags that end with "level". In this case, the user doesn't know the fully qualified name (FQN) of a specific tag and wants a short list of possible matches.

https://online.wonderware.[DOMAINSUFFIX]/apis/historian/v2/ProcessValues
?TagFilter=endswith(FQN, 'level').

See more TagFilter examples.

Scenario 2

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.

https://online.wonderware.[DOMAINSUFFIX]/apis/historian/v2/ProcessValues
?$filter=FQN+eq+'Baytown.tank_level'

Scenario 3

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

https://online.wonderware.[DOMAINSUFFIX]/apis/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

Scenario 4

This query contains three tags in the FQN array: one string, one discrete, and one analog. The analog tag in the array is a different tag than the one included in the Expression. The tags in the array will not be converted.

https://online.wonderware.[DOMAINSUFFIX]/apis/Historian/v2/ProcessValues?FQN="DataSource.Line3.analog",DataSource.Line3.string", DataSource.Line3.discrete",&StartDateTime="2021-07-11T00:00:00.000Z"&EndDateTime="2021-07-12T00:00:00.000Z"&Expression="UOM([DataSource.Line4.analog2],[K]) as [Analog2Alias]&RetrievalMode=Full

Scenario 5

This query retrieves the current value for the specified FQN.

https://online.wonderware.[DOMAINSUFFIX]/apis/Historian/v2/ProcessValues?RetrievalMode=StartBound&$filter=FQN eq 'MountainWaterTreatment.CartridgeFilterOutlet.TemperatureC'

Sample Output

{

"odata.metadata": "https://online.wonderware.[DOMAINSUFFIX]/apis/historian/v2/
$metadata#ProcessValues",

"value": [

{

"FQN": "20140805AK.TestSkipToken_0",

"DateTime": "2014-08-06T17:25:19.216486Z",

"OpcQuality": 192,

"Value": 39816,

"Text": "39816"

"TimeDeadband": 6000

"ValueDeadband": 1.25

},

{

"FQN": "20140805AK.TestSkipToken_0",

"DateTime": "2014-08-06T17:25:20.196Z",

"OpcQuality": 192,

"Value": 39817,

"Text": "39817"

"TimeDeadband": 6000

"ValueDeadband": 1.25

}

],

}