Skip to end of metadata
Go to start of metadata

This feature is new in Ignition version 8.1.0
Click here to check out the other new features
This function is used in Python Scripting.

Description

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 Permission Restrictions

This scripting function has no Client Permission restrictions.

Syntax

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 QualifiedValues. The quality code will indicate success or failure. If successful, the storage id of the annotation will be returned in the value. See Scripting Object Reference.

  • Scope

Gateway, Vision Clients, Perspective Sessions

Annotation Types

Possible annotation types are listed below.

TypeDescription
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. 
Code Examples
Example - Minimal Agruments
paths = ["[My-Provider]Station_1/ph"]

system.tag.storeAnnotations(paths)
Example - More Arguments
paths = ["[My-Provider]Station_1/ph"]
startTimes = [system.date.now()]
endTimes = [ system.date.addMinutes(startTimes[0], 1)]
types = ["range"]
data = ["some text"]

system.tag.storeAnnotations(paths, startTimes, endTimes, types,data)
Example - Updating Existing Annotations
# First, retrieve existing annotations based on some criteria. 
paths = ["[My-Provider]Station_1/ph"]
time = system.date.now()
annotations = system.tag.queryAnnotations(paths, system.date.addMinutes(time,-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.data], [a.storageId])
Keywords

system tag storeAnnotations, tag.storeAnnotations

  • No labels