Skip to main content
Version: 8.1

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

TypeParameterDescription
List[String]pathsA 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]startTimesThe start times of the events. If omitted, defaults to the current time.
List[Date]endTimesThe end times of the event, if applicable. If omitted, does not store an end time for the annotation. [optional]
List[Annotation]typesThe type id for the annotation. If not defined, "marker" will be used. See the Annotation Types for more details. [optional]
List[String]dataData for the annotation, such as text describing the meaning of the annotation. [optional]
List[String]storageIdsIf 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]deletedA 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 #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])

Keywords

system tag storeAnnotations, tag.storeAnnotations