Versions Compared


  • This line was added.
  • This line was removed.
  • Formatting was changed.



Stores annotations into the tag history system. Annotations are stored by the underlying historian implementations, so different providers may store in different ways, and some providers may not support annotation storage. All parameters are 1-to-1, so all provided lists should be of the same length. If a particular annotation doesn't need a parameter, that element can be None in the list.

Client permissions restrictions


system.tag.storeAnnotations(paths, startTimes, [endTimes], [types], [data], [storageIds], [deleted])

  • Parameters

List[String] paths - A list of tag paths to store for. The paths are equivalent to what would be used for a tag history query, and should specify the source provider as well. For example, "[HistoryProvider/Gateway:Provider]Path/To/Tag". This parameter is required, even if storage ids are included, because it is used to identify the underlying storage provider.

List[Date] startTimes - The start times of the events. If omitted, defaults to the current time. 

List[Date] endTimes - The end times of the event, if applicable. If omitted, does not store an end time for the annotation. [optional]

List[Annotation] types - The type id for the annotation. If not defined, "marker" will be used. See the Annotation Types for more details. [optional]

List[String] data - Data for the annotation, such as text describing the meaning of the annotation. [optional]

List[String] storageIds - If defined, the function will instead update the existing annotation instead of adding new ones, overriding existing values for the annotation with those provided by this function (if the corresponding delete parameter is True). Storage id is available on the Annotation object, and is returned as the result value from the storeAnnotations call. [optional]

List[Boolean] deleted - A list of booleans indicating that the individual annotation should be deleted. Requires storage id to be set as well. [optional]

  • Returns

A list of qualified valuesQualifiedValues. The quality code will indicate success or failure, and if . If successful, the storage id of the annotation will be returned in the value. See Scripting Object Reference.

  • Scope

Gateway, Vision Clients, Perspective Sessions

titleAnnotation Types

Possible annotation types are listed below.

noteA user created annotation. Used in cases specifically where a user adds the annotation (such as from the Power Chart's built-in interface).
rangeA date range that indicates a special area.
markerA singular point in time. 
traceA single point or date range that indicates an X-trace. 
titleCode Examples
Code Block
titleExample - Minimal Agruments
paths = ["[My-Provider]Station_1/ph"]

Code Block
titleExample - More Arguments
paths = ["[My-Provider]Station_1/ph"]
startTimes = []
endTimes = [[0], 1)]
types = ["range"]
data = ["some text"]

system.tag.storeAnnotations(paths, startTimes, endTimes, types,data)
Code Block
titleExample - Updating Existing Annotations
# First, retrieve existing annotations based on some criteria. 
paths = ["[My-Provider]Station_1/ph"]
time =
annotations = system.tag.queryAnnotations(paths,,-10),time)

# Iterate over the annotations, checking for some other criteria. In this case, we'll change "marker" types to "note" types. 
for a in annotations:
	if a.type == "marker":
		system.tag.storeAnnotations([a.path], [a.rangeStart], [a.rangeEnd], ["note"], [], [a.storageId])

system tag storeAnnotations, tag.storeAnnotations