Statesummary

Description

Retrieves state summary values for the specified tags.

URL

/StateSummary

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 for the retrieval cycle. This is always specified in UTC using the RFC3339 / ISO8601 format with the Z time zone designator. For example: 2016-09-03T18:44:09.352247Z

• EndDateTime=[DateTimeOffset]
  The ending date and time for the retrieval cycle. This is always specified in UTC using the RFC3339 / ISO8601 format with the Z time zone designator. For example: 2016-09-03T18:44:09.352247Z

Optional Parameters

• RetrievalMode=[string]
  Possible values are: Cyclic, Full.
  Default is Cyclic.

• Resolution=[Int]
  In milliseconds. Any positive integer.

• OPCQuality=[Int32]
  OPC quality. Normal OPC quality retrieval logic is applied if:

  All the point found and processed for this row have GOOD quality. If they all have the same GOOD quality, then that quality is returned.

  If there is a gap in the entire calculation cycle, then BAD quality is returned for the tag.

  For any other scenario with any mixture of GOOD and BAD points, a DOUBTFUL OPC quality (64) is returned.

• Text=[string]
  Non-numeric state.

• Average=[Double]
  Average time in this state among all occurrences of this state during this retrieval cycle, including state occurrences that fall only partially within the period.

• AverageContained=[Double]
  Average time in this state among all occurrences of this state during this retrieval cycle, excluding state occurrences that fall only partially within the period. An occurrence that was partially contained in two or more consecutive storage cycles is converted to a contained state within the retrieval cycle if possible.

Optional Parameters

• Minimum=[Double]
  Minimum time in this state among all occurrences of this state during this retrieval cycle, including state occurrences that fall only partially within the period. An occurrence that was partially contained in two or more consecutive storage cycles is converted to a contained state within the retrieval cycle if possible.

• MinimumContained=[Double]
  The minimum of the contained times in this state among all occurrences of this state during the entire retrieval cycle, excluding state occurrences that fall only partially within the period. An occurrence that was partially contained in two or more consecutive storage cycles is converted to a contained state within the retrieval cycle if possible.

• Maximum=[Double]
  Maximum time in this state among all occurrences of this state during this retrieval cycle, including state occurrences that fall only partially within the period. An occurrence that was partially contained in two or more consecutive storage cycles is converted to a contained state within the retrieval cycle if possible.

• MaximumContained=[Double]
  The maximum of the contained times in this state among all occurrences of this state during the entire retrieval cycle, excluding state occurrences that fall only partially within the period. An occurrence that was partially contained in two or more consecutive storage cycles is converted to a contained state within the retrieval cycle if possible.

• Total=[Double]
  Total time in this state during this retrieval cycle, including state occurrences that fall only partially within the period.

• TotalContained=[Double]
  Total time in this state during this retrieval cycle, excluding state occurrences that fall only partially within the period. An occurrence that was partially contained in two or more consecutive storage cycles is converted to a contained state within the retrieval cycle if possible.

• Percent=[Double]
  Percent of the time during this retrieval cycle that the tag was in this state, including state occurrences that fall only partially within the period.

• PercentContained=[Double]
  The precentage of the entire retrieval cycle time that the tag was in this state, excluding state occurrences that fall only partially within the period. This is a ratio between StateTimeTotalContained and StateTimeTotal expressed as a percentage in the range 0 to 100. An occurrence that was partially contained in two or more consecutive storage cycles is converted to a contained state within the retrieval cycle if possible.

• Count=[Int64]
  The number of times the state occurred within the retrieval cycle, including states that only partially occur in the cycle.

• CountContained=[Int64]
  The number of times the state occurred fully contained within the retrieval cycle. States that only partially occur in the cycle are not counted.

• LastDateTime=[DateTimeOffset]
  The timestamp for the last received value.

Sample Query

Scenario 1

This query produces a list of tags that end with "pump_03". 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/StateSummary?TagFilter=
endswith(FQN, 'pump_03').

See more TagFilter examples.

Scenario 2

This query specifies no start or end time and no resolution.

https://online.wonderware.[DOMAINSUFFIX]/s/ik97r5/apis/historian/v2/StateSummary
?$filter=FQN eq 'Baytown.pump_03'

In this case, these defaults are used for the returned results:

• EndTime defaults to DateTime.UtcNow

• StartTime defaults to one hour before EndTime

• Resolution defaults toTimespan

• Count defaults to1 (number of returned rows)

Scenario 3

This query specifies only StartTime and Resolution (600000ms, or 10 minutes), but no EndTime.

https://online.wonderware.[DOMAINSUFFIX]/s/ik97r5/apis/historian/v2/StateSummary
?$filter=FQN eq 'Baytown.pump_03' and StartDateTime ge
2017-06-29T00:00:00Z&Resolution=600000

In this case, Insight assumes:

• EndTime defaults to DateTime.UtcNow

The number of rows returned (Count) depends on the StartTime and EndTime.

Scenario 4

This query specifies only EndTime, but no StartTime or Resolution.

https://online.wonderware.[DOMAINSUFFIX]/s/ik97r5/apis/historian/v2/StateSummary
?$filter=FQN eq 'Baytown.pump_03' and EndDateTime le 2017-06-29T00:00:00Z

In this case, Insight assumes:

• StartTime defaults to one hour before EndTime

• Resolution defaults toTimespan

• Count defaults to1 (number of returned rows)