Skip to main content

String Replacement

Prerequisites​

Before configuring String Replacement, ensure you have:

Overview​

MQTT Engine supports String Replacement for both MQTT topics and payloads that are used to create Ignition tag paths. This feature is commonly used with Custom Namespaces when you do not have full control over the topics or payloads being published.

String Replacement can also be used with the Sparkplug B namespace when metric names contain characters that are not valid in Ignition tag names.

While MQTT and Sparkplug support characters such as ., &, %, and =, Ignition does not allow these characters in tag paths or tag names. String Replacement allows MQTT Engine to replace unsupported characters or character sequences before creating tags. For more information on Ignition tag naming rules, see the Ignition User Manual: Tags.

String Replacement Usage​

String Replacement can be configured for any Custom Namespace or the Sparkplug B namespace.

The feature supports:

  • Replacements executed in Order Index order (lowest to highest).
  • Single character to single character replacement.
  • String to string replacement.
  • Character or string removal (replacement with nothing).
  • Regular expression (regex) pattern matching with replacement by a string, character, or nothing.
  • Empty or null replacement strings.

Note

String replacements are only applied to characters that become part of the Ignition tag path. Tag values are not modified.

Examples​

  • Remove all @ characters.
  • Replace all @ characters with _.
  • Replace all abc strings with def.
  • Replace all characters between the literal strings start and end with _ using a regular expression.

Determining Required String Replacements​

When MQTT Engine creates Ignition tags, tag names must conform to Ignition's naming rules.

First character​

The first character of a tag name must be one of the following:

  • Letter (Unicode Letter category)
  • Number
  • Underscore (_)

Remaining characters​

All remaining characters may be:

  • Letters
  • Numbers
  • Underscores (_)
  • Spaces
  • The following special characters:
    • '
    • -
    • :
    • (
    • )

All other special characters are invalid in an Ignition tag name.

Identifying Required Replacements​

To determine the required String Replacement rules:

  1. Review the published MQTT topic and, if applicable, a sample JSON payload.
  2. Identify any characters that may not be valid in Ignition tag names.
  3. Compare those characters against the Ignition naming rules above, or test creating a tag in the Ignition Designer.
  4. If the tag cannot be created, configure a String Replacement rule for the invalid character or string.

Example​

Consider the following MQTT message:

Topic

a/b

Payload

{
  "tag 1": 123,
  "tag@2": "some.value"
}

A Custom Namespace subscribed to a/# will receive this message, but MQTT Engine cannot create the tag because @ is not a valid character in an Ignition tag name.

The following error is logged:

INFO | jvm 1 | 2022/01/06 11:33:29 |
E [c.c.m.e.g.j.JsonPayloadHandler] [19:33:29]:
Failed to handle tagPath - not adding tag: a/b/tag@2 - Remove it from future payloads

Configure a String Replacement rule to replace @ with _.

After applying the rule, MQTT Engine creates the tag successfully using:

tag_2

instead of:

tag@2