Creating a dynamic message body

Often, when you set up the body of a message that the system is to generate in response to some event, you want to include information in the message that is based on the current situation. For example, you might want to include a purchase order number, the vendor's name, or the new credit limit proposed for a customer. To accomplish this, you can use simple or more complex expressions.

Note: When creating these expressions, keep in mind these points:
  • You can also use these techniques to create a dynamic Subject line for a message.
  • These techniques also apply to HTML message bodies. In such cases, you must embed the HTML code within appropriate expressions. At run-time, then, the system conveys the HTML body in such a way that the email server signals the email client to use the embedded tags to interpret the text and render the message body with HTML formatting.
  • This list is not an exhaustive list of the kinds of expressions you can use effectively within a BODY (or SUBJECT) parameter construct. These examples show some of the most common or most useful expressions you can use.

Example: Using a SUBSTITUTE expression

Perhaps the most common type of expression to use for a message body is the SUBSTITUTE expression. With this type of expression, you can create a basic string for the message with replacement zones marked by curly braces { }. The values of these curly brace zones are provided at run-time, usually by referencing fields on forms.

For example, suppose you want your message body to say: "We have a new customer. Please see customer number <number> for customer: <customer name>." In this case, you want the <number> to be replaced with the new customer's ID code and the <customer name> to be replaced with the new customer's name.

To accomplish this with a SUBSTITUTE expression, you would create this BODY parameter:

BODY( SUBSTITUTE("We have a new customer. Please see customer number {0} for customer: {1}.", P("custNum"), P("custName") ) )

At run-time, when this event executes, the system retrieves the value of the custNum and custName fields and places the values in zones {0} and {1}, respectively.

For more information about SUBSTITUTE expressions, see SUBSTITUTE.

Note:  You can enhance any of the other, remaining examples by wrapping them within a SUBSTITUTE function to provide additional contextual information.

Example: Using a GC (Global Constant) expression

One of the more useful expressions to use within a body message is a global constant expression. You can set up such expressions as templates to be reused within a single handler, substituting a different variable value each time it is used.

For example, you might have a handler set up to obtain multiple approvals from a series of individuals, each approval being dependent on the previous one. You can create a global constant that contains the basic text of the message, with placeholders for variable values that change for each approval as the handler works through the sequence.

For working examples, see Sample scenarios.

In a different situation, you might have two prepared messages, either of which might be used, depending on a user's choice or action. For example, you might have one message, contained within a global constant, that indicates that the recipient approved an action. You might have a second message, contained within a different global constant, that indicates that the recipient rejected the request. In cases like this, you might have two different GC expressions like these:

BODY( GC(StdApprovalMessageBody) )

BODY( GC(StdRejectionMessageBody) )

If you need to select between these two at run-time, you could set up the BODY statement like this:

BODY( IF( P("POCost") > 10000, GC(StdApprovalMessageBody), GC(StdRejectionMessageBody) ) )

For more information about GC expressions, see GC.

Example: Using a FILECONTENTS expression

Suppose you have a prepared text (*.txt) file somewhere on a network shared drive that you want to use as the content for your message body. In this case, you could use a FILECONTENTS expression for the generated message. For example:

BODY( FILECONTENTS("X:\mg_app\Event\Message\Body\myPreparedMessage.txt") )

where "X:\" represents the drive on this the text file exists.

To use any of a selection of text files, depending on some action or choice by the user, for instance, you could use a construct like this:

BODY( FILECONTENTS("X:\mg_app\Event\Message\Body\" + IDO() + EVENTNAME() ".txt") )

For more information about FILECONTENTS expressions, see FILECONTENTS.

Example: Using a DBFUNCTION expression (T-SQL function)

You might have a T-SQL database function that you want to use to determine what the message body is to say. In this case, you could set up your BODY statement like this:

BODY( DBFUNCTION( "MsgBodyFunction", EVENTNAME(), IDO(), P("RowPointer") ) )

For more information about DBFUNCTION expressions, see DBFUNCTION.