system.tag.storeAnnotations

New in 8.1.0

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

Type	Parameter	Description
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.

Type	Description
note	A user created annotation. Used in cases specifically where a user adds the annotation (such as from the Power Chart's built-in interface).
range	A date range that indicates a special area.
marker	A singular point in time.
trace	A single point or date range that indicates an X-trace.

Code Examples

Example #1 - Minimal Agruments

paths = ["[My-Provider]Station_1/ph"]
 
system.tag.storeAnnotations(paths)

Example #2 - 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 #3 - 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])