Version: 18
restore

Contents

Summary

Guidance and examples for using tags in instructions.

Tag Types

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

  • coverage tags which can be used in the coverage for questions and actions to help target specific devices
  • freeform tags which 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.


On this page:

Coverage

Also known as scopable in Agent methods documentation. 

These tags are used when defining the coverage for questions and actions. Once set by an action, the Agent regularly reports its list of 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 the system determines coverage for questions and actions. Instructions which query tag contents, do so by querying the Agent, they do not query the Master database; the database is used only for coverage.

The maximum length of a tag name is 16 characters, and the maximum length of a tag value is 32.

Coverage tags are stored on the Agent as a list which consists of a separator and NAME=value for each tag plus a final separator at the end of the list. The list of coverage tags including separators must not exceed 511 bytes. Any tags that exceed this limit are not set. 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. 

Freeform

Also known as non-scopable in Agent methods documentation.

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.

The list of freeform tags consists of a separator and NAME=value for each tag plus a final separator at the end of the list. There is no limit to the number of freeform tags or the length of the list, and no limit to the length of tag name or tag value.

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.

Coverage and freeform tags are stored internally as two distinct lists.

Each list uses | as a separator between each NAME=Value and at the start and end of the list. For example: |DEPT=Sales|LOCATION=London|COUNTRY=UK|REGION=EMEA|

|| is an empty tag list.

A tag name must be unique within a list, so that 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.

Coverage and freeform tags can share the same names and they are distinct.

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).

When setting a tag, you will need to cast a non-text value as text.

Example
@toset = 99;
@toset = SELECT CAST(Value AS text) AS Value FROM @toset;
Tagging.Set(Name: "EXAMPLETAG", Value: @toset.Value, Scopable: false);

Defining Coverage Tags

Users of the Tachyon Explorer UI can target specific devices based on various attributes including coverage tags. A coverage tag may only be used to target devices if the tag's name and allowed values are already defined in the Tachyon system Custom Properties admin page. Instructions can then be configured to prompt users for selection of defined name and values.  Whilst it is possible to set other coverage tag names and values on Agents, it is best not to do this because they cannot be used for coverage until their names and values are defined in Custom Properties admin page.  More details on the Coverage tag workflow and tutorials for administrators are given in Tachyon version documentation, for example using Tachyon 3.1 see: Tagging Tachyon Agent devices

Coverage Tag is a type of custom property, and is currently the only type of custom property that is configurable in the Custom Properties admin page. 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. 

It is possible for a coverage tag to exist on Agents which do not exist as a Custom Property. This may occur because an instruction has set a coverage tag without reference to Custom Properties, or a Custom Property has been deleted from the system after being set on Agents. It is good practice to define custom properties in the admin page, and then use the instruction Set coverage tag %tagname% to %tagvalue% which uses "value picker" parameters that let you select a tag name and value based on defined custom properties. If you set a coverage tag on an Agent that does not exist as a custom property, then it will behave like a freeform tag and you will not be able to use it to set Coverage in the Tachyon Explorer. Furthermore, you will use up space in the 511 character length of the coverage tag list. 

See the following links in the SDK for details about value picker parameters.

While on the subject of coverage tags that don't exist as defined custom properties. Consider a hypothetical situation where coverage tags have been defined, and set on many Agents, and then the Tachyon server hardware 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) to query all devices for details of all coverage tag names, and use this to re-define coverage tags.  Alternatively you could start over again by establishing new tags, and using the Clear method to delete existing tags on devices.