Version: 5
restore

Contents

On this page

Tag Types

Tachyon Agent devices can have a number of custom tags assigned using Tachyon and the Tachyon agents. There are two types of tag: 

  • coverage tags, which can be used in the scopes for questions and actions to help target specific collections of devices
  • freeform tags that can be queried and set using specific questions and actions

Tags are arbitrary NAME=value pairs assigned to devices, and once assigned remain in the Agent's persistent store until explicitly deleted. Tags are set or deleted using actions and queried using questions. The differences are described below.

Coverage

Also known as scopable tags, which is the terminology using in Agent methods.

These tags are used when defining the coverage for questions and actions. A Tachyon Custom Properties Administrator must define the names and values for Coverage tags before they can be applied to devices using Coverage tag actions. More details on the Coverage tag workflow and tutorials for administrators are given in Tachyon version documentation, for example for Tachyon 3.1 see: Tagging Tachyon Agent devices.

Once set by an action, the Agent reports coverage tags back to the System where they are stored in the Tachyon Master database for each device (in the Device table) which is how they can be used to define coverage for questions and actions.

The Agent regularly reports back its list of tags. The list consists of a separator and name=value for each tag plus a final separator at the end of the list. The entire list must not exceed 511 bytes. Any tags that exceed this limit are not reported back. Only the tags reported back by each Agent can be used for coverage. Therefore the length of tag names and values should be kept short if many different tags are to be used. The maximum length of a tag name is 16 characters, and the maximum length of a tag value is 32.

Consider a hypothetical situation where coverage tags have been defined, and set on many Agents, and then the Tachyon server fails and the Master database is lost. If the server is rebuilt using a new database, then you would probably want to re-instate the same coverage tags. If you did not have these documented, then you could use the GetAll method (see Tag Methods below) to fetch details of all coverage tag names and most values, and use this to define coverage tags.  Alternatively you could start over again by establishing new tags, and using the Clear method to delete existing tags on devices.

Freeform

Also known as non-scopable tags, which is the terminology using in Agent methods.

Freeform tags exist purely on the Agent, where they can be set, their values fetched, and checked for existence. They cannot be used when defining the coverage for a question.

Freeform tags can be set with arbitrary names and values that are defined only when running a Freeform tag action.

Tag Storage

Tags are stored on devices in Agent persistent storage, and as such persist during re-installation and upgrades. They are deleted only if explicitly deleted or the persistent storage is deleted. 

Tag names are alphanumeric strings, which are case-insensitive but returned in upper-case.

Tag values are alphanumeric strings, with case preserved. That is, a number would be represented as a string such as "99", and can be empty (zero-length string) if the presence or absence of a tag is sufficient.

Assigning a value to a tag will create the tag if it does not already exist or overwrite the tag's value if it was already there.

A coverage and freeform tag can share the same name and they are distinct.

Tags are store internally in a tag list as NAME=Value with a separator | at the start and end. For example: |DEPT=Sales|LOCATION=London|COUNTRY=UK|REGION=EMEA|

|| is an empty tag list.

Tag Methods

The following methods existing in the Agent Tagging module:

  • Page:
    Tagging.Check — Tests the existence of a named tag of a specified type, optionally with the specified value.
  • Page:
    Tagging.Clear — Delete all tags of the specified type.
  • Page:
    Tagging.Count — Get the quantity of tags of the specified type.
  • Page:
    Tagging.Delete — Delete the named tag of the specified type, and indicate if it originally existed.
  • Page:
    Tagging.Get — Indicate whether a named tag of the specified type is present and return its value if present.
  • Page:
    Tagging.GetAll — Fetch the tag list (containing all tags) of the specified type.
  • Page:
    Tagging.Set — Set (or change if already set) the named tag of the specified type to the specified value.

Each method requires the tag type to be specified as either scopable (true) or non-scopable (false), with default scopable (true).