Message Variables New

A variable is a name in braces, such as {groupName}, that OAS replaces with text from the tag, its groups, the message or the system when it publishes. One setting can then give a different result for each tag: plant/{groupPathSlash} publishes each group's tags on a topic of its own, and {site}/{area}/{tagShortName} fills a field with Dallas/Plant/Speed.

This page lists every variable, where each driver reads them, and how the drivers differ.

Where variables can be written

Settings that may look as if they take a variable, but do not:

Writing a variable

What counts as no value:

• an Id part past the last |, or with nothing between two bars - A||B has no {tagIdPart2},
• a level no group above the tag has,
• a group variable, such as {groupPath}, {groupName} or {hierarchyPath}, on a tag that is in no group,
• an unset {workCenterType} or {workUnitType},
• an empty property,
• {schemaName} with Output Format Default,
• on the broker and in Data Test opened from the library, {driverName},
• on the broker, {tagSeq0} and {tagSeq1},
• on Snowflake, {topic}, {schemaName}, {seq0} and {seq1}.

The variables

The examples are for the tag Acme.Dallas.Plant.Line1.Speed.Value, where:

• the groups Acme, Dallas, Plant and Line1 have the ISA-95 levels Enterprise, Site, Area and Work Center,
• the site's ID is DAL,
• the tag's Units property is rpm,
• the tag is listed in a driver's Tags To Publish with the Id SPD-01|Hall_A.

Topic says whether Publish Topic Id accepts the variable; the ones it does not accept change with every value or every message. MQTT only means Kafka accepts the variable too, but it always gives a /, which a Kafka topic may not hold, so on Kafka the tag is never published.

The tag

One entry of a tag array or tag map

These work only inside a tag array or tag map. Anywhere else they are an error.

For a number that must always mean the same point, such as pointID_{tagSeq1}, use {tagSeq1}.

The tag's group

The group path variables use the groups' real names. The level and hierarchy variables use a group's export name override when it has one, and give the same text as the Hierarchy mapping.

The message and the system

Where a variable may be used inside a schema

When a message holds many tags, a field outside the tag array or tag map is built once for the whole message:

• it may use the group, message and system variables,
• a tag or entry variable there is an error, just as mapping that field to a tag's value is,
• a group variable there means one message per group.

MQTT driver

• Topic. A Publish Topic Id that holds a variable a topic may use is a topic pattern. Each tag goes to the topic the pattern gives it, and tags of one publish that share a topic share a message. This works with every Output Format, including Default. The topic a tag gets may not contain + or #. The slash variables give one topic level per group. Topics are worked out again once a minute, so a renamed group or a changed property is followed within a minute, without a restart.
• Message. Variables are read in a schema only with Output Format ISA-95 Lite or Custom AVRO Schema. The Default payload has no variables.
• Many tags in one message. With Publish All Tags As One Topic on, Batched Messages on and a schema with a tag array or tag map, {seq0}, {seq1} and {tagCount} count the tags in the message. A message is split by Max Tags Per Publish, and by group when a field outside the tag array reads a group variable.
• Several Ids. A tag listed in Tags To Publish under several Ids gives one entry per Id, each with its own {tagId} and parts, when the mapping or the topic reads the Id. A tag map whose key does not read the Id keeps the last Id, and that is logged once for the tag. A pattern that reads the Id gives each Id its own topic.

Kafka driver

• Topic. A topic pattern works as it does on MQTT, including the refresh once a minute, and the Kafka topic is created under the filled-in name. The topic a tag gets must also be a legal Kafka topic name: 1 to 249 characters of A-Z, a-z, 0-9, ., _ and -, and not . or ... A tag whose topic breaks the rule is not published, and System Errors gets one entry for it. The line under Publish Topic Id in the web app warns about it before you apply. In practice:
  • use {groupPath}, {tagPath} or {hierarchyPath} - their slash forms always fail,
  • a group, tag or override name with a space, or any character outside that set, fails,
  • {property:Name} fails when the property's value holds such a character.
• Message. As on MQTT, variables are read only with ISA-95 Lite or Custom AVRO Schema. The Default message, with or without a Schema Registry, has no variables.
• Many tags in one message. Only with Custom AVRO Schema, a tag array or tag map, Batched Messages on and Publish All Tags As One Topic on. Otherwise every message holds one tag, so {seq0} is 0, {seq1} is 1 and {tagCount} is 1.
• Subject Name. Variables are not allowed. The schema is registered once, when the driver connects, under that one name, and every topic's messages carry its ID. With a topic pattern and Enable Schema Registry on, the name is required: left blank, the driver does not connect, raises a schema alarm, and the web app shows an error on the setting. A subject for each topic is not supported.
• Several Ids. As on MQTT.

MQTT broker

The broker reads variables in the library schema a client names, on a schema topic such as Sine.Value/plant-a-v2 or a $schema/ group topic such as $schema/plant-a-v2/Plant/Line1/+. It has no Tags To Publish list and no driver name, so a few variables give something else - see What differs.

A $schema/ group topic that sends one message per tag gives what a schema topic gives, except {topic}, which is the tag's group topic.

One message per group, under $schema/default/ or with a schema that has a tag array or tag map ($schema/line-batch/Plant/Line1), gives:

Snowflake driver

A column's value can be a Custom Format: in the Column Mapper, set the column's source to Custom Format and write text and variables, such as {site}-{tagName}. Each row is filled for its own tag, and the result goes into the column as text, so the Column Mapper sets the column's type to STRING. See Custom Format in the Snowflake Config Reference.

A column name cannot hold a variable. It is the table's column, used exactly as written, and a column name with braces is an error in the Column Mapper and in the driver's settings.

A row is one tag with no message around it, so a few variables give something else:

A row left out because a variable has no value is logged once in System Errors, naming the variable and the tag. A Constant is still sent exactly as typed, braces included.

What differs between the drivers and the broker

Every variable not listed here gives the same text wherever it is read.

Where next

• Message Schemas - the schema library, the schema editor, and tag arrays and tag maps.
• MQTT Config Reference - topic patterns and Batched Messages on the MQTT driver.
• Kafka Config Reference - topic patterns and the Schema Registry on the Kafka driver.
• MQTT Broker - schema topics, group topics and one message per group.
• Snowflake Config Reference - the Column Mapper.