qbo.Message Substitution

posted Jan 6, 2017, 5:48 PM by Eric Patrick
The qbo.Message module supports curly-brace substitution for Subject, BodyHTML and BodyText fields. For example:

Message/Save?Object=Contact&ObjectID=1&Subject=Hello {Suffix} {LastName}

will replace Suffix and LastName with the corresponding fields from the Contact row for ContactID = 1. Technically, each curly brace expression is evaluated against the Message's parent's summary data. If a full XPath expression is not used, we use //{expression} (e.g. //Suffix or //LastName in the example above).

There are some use cases where this can be inappropriate. For example, email body's may contains text that include curly-brace expressions that are not intended to be XPath expressions. In such situations there are two application settings that apply:
  • qbo.Message.Properties.Settings (maintained from Design > Configuration > Modules > Message, Settings panel)
    • MergeSubstitution: boolean, defaults to true
    • SuppressSubstitutionErrors: boolean, defaults to true
If SuppressSubstitutionErrors is true, Message/SetDefualts will ignore any errors encountered when trying to evaluate an XPath expression during substitution. For example:

Message/Save?Object=Contact&ObjectID=1&BodyText=This is not valid xpath: {Bad XPath Here}

In this case, this is the same as:

Message/Save?Object=Contact&ObjectID=1&BodyText=This is not valid xpath:

If SuppressSubstitutionErrors is false, the same call will raise an error.

In some cases, you may have content that uses curly-brace expressions that are not intended to be XPath expressions. For example, I might post the contents of this blog post as a Message. To prevent the Message module from performing the substitution, I can override the default MergeSubstitution setting with a parameter:

Message/Save?Object=Contact&ObjectID=1&BodyText=This is a lesson on {curly braces}!&MergeSubstitution=false

Note that if the message is template-based, MergeSubstitution parameters do nothing; substitution is always attempted. For example:

Message/Save?Object=Contact&ObjectID=1&Template=MyTemplate&BodyText=This is a lesson on {curly braces}!&MergeSubstitution=false

is the same as:

Message/Save?Object=Contact&ObjectID=1&Template=MyTemplate&BodyText=This is a lesson on {curly braces}!








Comments