Dynamic Text

Dynamic Notification Text

Notification bodies or some [external actions](/config/globals/external.html] fields may optionally contain any amount of dynamic text indications. These are indicated between $ characters and refer to rule engine variable of the same name. At runtime, dynamic text will be filled with the variable value. For example, $var1$ would be expanded at runtime to contain the contents of the variable named var1.

Dynamic text may also include a Lua string format pattern (with or without a leading %) after a : character. For example, the text bodies $balance:.2f$ and $balance:%.2f$ are identical and will both present the contents of the variable named balance formatted to two decimal places.

Note that Lua string format patterns must match the expected type of dynamic text or a runtime error will be thrown.

If no format pattern is specified, the pattern %s (i.e. a normal string) will apply.

Dynamic text can also include balance information provided by the OCS. In these cases, the specific balance component must be specified after the balance name separated by a period:

• balance1.units will use the balance value of the balance named balance1.
• balance1.currency will use the currency translation of the balance named balance1.

For both balances and variables, a default value may be configured for use when the specified value is not present. This may be assigned by adding | after the variable identifier and/or format definition, followed by the default value to use. A default may be used when:

1. A variable has no value. Note that an empty string or a boolean false is still a value.
2. A balance provided by the OCS has no unit value. Note that a zero or negative value is still a value.
3. A balance provided by the OCS has no currency translation. Note that the OCS-provided value will only be used if no translation exists and no default is defined.

The character ! can be used to indicate that any special qualities of the next character should be ignored. If a literal ! character is required, escape it with a leading !, i.e. !!.

As a fully-worked example, given the following configured dynamic text:

Your balance is $cash.currency|€$$cash.units|0:.2f$. You have $percent|100:.1f$% of your $units|items$ remaining and !$$promo.units|0:.0f$ promotional cash.

… it might be transformed at runtime into:

Your balance is $1.20. You have 10.2% of your free minutes remaining and $5 promotional cash.

Where:

• The balance information from the OCS for the balance named cash is 1.2 and for the balance named promo is 5.2.
• The currency translation for the cash balance is defined as $.
• The rule engine variables percent and units are set as 10.21 and free minutes, respectively.

If no values were available for substitution, the runtime output would be:

Your balance is €0.00. You have 100.0% of your items remaining and $0 promotional cash.