Appendix E: Using Conditional Blocks

Adding conditional blocks to the body of an email job is a powerful way to personalize the content of the message for individual recipients. Conditional blocks act much the same way that merge fields do in that their use is dependent upon the recipient data available in the mail job. Judicious use of conditional blocks can also save time and resources by allowing one job to contain different content for different recipients that would otherwise have to be sent in multiple jobs.

Conditional blocks are sections of text that are inserted into a message based on a conditional statement. If the condition is “true”, a particular section of text will be inserted into the message. If the condition is “false”, the text will not be inserted. An “ELSE” clause can be included as part of the conditional statement so that a different section of text will be inserted into the message when the condition is “false”.

Important: Conditional blocks use a significant amount of processing time. Use with care for jobs with a large volume of recipients. If messages will be substantially different for different recipients, then it may be more efficient (and easier to test) if the recipients are split up among multiple jobs with fewer conditional blocks, rather than trying to fit many different messages into one job with a complex conditional block structure.

Syntax for Conditional Blocks

The syntax of a conditional block is composed of directives and operators. A conditional block is coded by using the ".BB" (begin block), the ".EB" (end block), and the “.ELSE" directives. Comments can be added without appearing in the final message by placing a “.*” before the text containing the comment. Each directive must be on a line by itself, starting as the first character of the line. Conditional directives are not case sensitive.

Table 7 Conditional Directives

.bb

Begins a conditional block. Must begin any block and must contain the condition to be evaluated on the same line.

.else

Conditional "else". If the condition specified in .bb evaluates "false", then execute the code in this part of the block.

.eb

End conditional block. Must be the last line of any block.

.*

Precedes comment lines.

 

A conditional block always starts with the .BB directive followed by a “condition” on the same line. The .EB directive ends the conditional block. Fields used in a condition are preceded by an ampersand (“&”), but are not followed by a semicolon (“;”).

The syntax for a basic LISTSERV Maestro conditional block looks like this:

.bb condition_to_be_evaluated

text to be included when the condition is met

.eb

The .ELSE command is used to execute the code in the block if the condition is false. Instead of not including any text if the condition is false, a different text can be included. For example, if you wanted to add the recipient’s name to the salutation of a message so the greeting starts with “Dear fullname”, but not all of the recipient records have a name entered in the “fullname” field, then the use of a conditional block can ensure a salutation for all messages. Those recipients that have a name in the “fullname” field (condition is “true”) would receive a message with their name inserted, and those that do not have a name in the field (condition is “false”) can have a generic greeting inserted into the message instead.

Such a conditional block might look like this:

.bb &fullname ^= "" 

Begin block directive.

 

Ampersand and column name represents the recipient data to perform the operation on.

 

Operator characters that represent the operation performed on the data. In this case, the conditional expression checks that the value in the “fullname” column is “not equal to an empty string” or is not blank.

 

Dear &fullname;, 

The text to be inserted if the condition is “true”.

In this case, if there is data in the field “fullname” it will be inserted here using the merge-field to create a line that reads “Dear Anne Smith,” for example.

 

.else

 

The else directive is inserted to allow a different text to be used if the condition is false. In this case, if the field “fullname” has no data, another salutation will be used.

 

Dear Valued Customer,

 

The text to be inserted if the condition is false. In this case, a generic salutation.

.eb

 

End block directive.

 

Nesting Conditional Blocks

Conditional blocks can be nested to any depth, creating opportunities to insert more than two pieces of text, depending on the conditions. For example, if the second condition is false, another variation of the text is inserted, and if the third condition is false, another variation of the text is inserted, and so on. An example of a nested conditional block looks like this:

.bb condition_to_be_evaluated

  text to be included when the condition is met

.else

.bb condition_to_be_evaluated

  text to be included if the first condition is not met but the second condition is

.else

 text to be included if neither the first nor the second condition is met

.eb

.eb

Conditional Operators

The condition that is evaluated is created by making a comparison against recipient data. Operator symbols make up the statement and appear in a table below. Operators are not case sensitive. However, == (strictly equal to) and ^== (not strictly equal to) are available when case must be respected. String literals within a statement must be enclosed within quotation marks if they contain spaces.

Boolean operators “AND” and “OR” may be used within the statement. If used, the sub-expressions must be enclosed within parentheses. For example, for this conditional block to be true both expressions must be met; the recipient must be in New York State and in New York City to see the text about winning sunglasses:

.* For residences of New York, NY

.bb (&state = NY) and (&city = “New York”)

Congratulations! You have won a free pair of XYZweb sunglasses!

.eb

For the next conditional block to be true, only one of the expressions must be met; the recipient is either in New York State or in New York City. Recipients in “Albany, NY”, “New York, NY”, and “New York, CA” will see the text about winning sunglasses.

.* For residences of any New York

.bb (&state = NY) or (&city = “New York”)

Congratulations! You have won a free pair of XYZweb sunglasses!

.eb

Table 8 Conditional Operators

=

is equal to (case insensitive)

==

is strictly equal to (case sensitive)

is greater than

is less than

=>

is greater than or equal to

=<

is less than or equal to

=*

matches wildcard expression

^

negation - used in conjunction with the other mathematical operators, for instance, "^=" means "is not equal to"

IN

The specified text is found in the space-separated data provided. For instance,

.bb DEC IN &*DATE

The server’s internal variable &*DATE outputs the day’s date in the format "Day, dd Mon yyyy hh:mm:ss -TZ". This statement would evaluate true if the date were any day in December, and false for any other day of the year.

NOT IN

The specified text is not found in the space-separated data provided

Testing Conditional Blocks

Any number of conditional blocks can be inserted into the body of a message. Conditional blocks will be processed and resolved by LISTSERV during delivery and will not appear as part of the final message that is sent to recipients. Figure 129 shows a plain text message that contains conditional blocks and merge-fields. Figures 130 and 131 show variations of the resulting message when certain conditions are met.

One of the most important steps to perform when using multiple conditional blocks is extensive testing. Send messages to test every condition and combination of conditions to ensure that your conditional text matches up with your recipient data in the expected manner.

Important: Any basic syntax errors that are detected when the job is transferred to LISTSERV will generate an error message from LISTSERV that will be displayed in the Maestro User Interface.

However, if there are mistakes in the syntax of the conditional statement that turn up when the conditions are evaluated for each recipient, the test messages will not be sent, although they will appear to, because LISTSERV cannot process the job with incorrect coding. No error message will be displayed in the Maestro User Interface. Errors of this nature will be reported in the LISTSERV logs and an email message will be sent to the LISTSERV Postmaster. If your test messages are not delivered in a reasonable amount of time, contact your LISTSERV administrator for assistance diagnosing the problem.

Presented in Figure 129 is an example of a detailed plain text email message using mail-merge and complex conditional blocks. Each variable and combination of variables needs to be tested before the job is sent out. Some of the resulting test messages for particular combinations are presented in Figures 129 and 131.

 

Figure 131 Plain Text Message with Conditional Blocks

Happy birthday!

To celebrate the occasion, XYZweb is pleased to credit your account with $10.00 in birthday credits. You can spend these credits on anything in our online store, but there's a catch! They will expire in a week if you do not use them! So wait no further and go to your personalized web page at:

&PERS_URL;

.* Special offer for people who turn 18

.bb &age = 18

Now that you are 18, you can finally do what you have been waiting for all your life - sign up for your very own XYZweb online cash management account! We are waiving the first year's fee if you apply within the next 2 weeks! Apply now at: http://www.XYZWeb.com/bday/1234&=18badgrz

.eb

.* Two randomly selected people every day get a free T-shirt. Note: &*index .* is randomized with every run. If we ran the job twice, the prize would go .* to different people

.bb &*index <= 2

Congratulations! You have won a free XYZweb T-shirt!

.eb

.* Another 10 randomly selected people get a free baseball cap

.bb (&*index > 2) and (&*index <= 12)

.* Make that a free pair of sunglasses in Texas!

.bb (&country = USA) and (&state = TX)

Congratulations! You have won a free pair of XYZweb sunglasses!

.else

Congratulations! You have won a free XYZweb baseball cap!

.eb

.eb

.* Special for AOL users

.bb &*to =* "*@aol.com"

Did you know that you can access XYZweb's store directly from AOL?

Click on keyword XYZWeb and land on your personalized page.

.eb

The resulting message to a person using AOL and turning 18 would read:

Figure 132 Resulting Recipient Plain Text Message

Happy birthday!

 

To celebrate the occasion, XYZweb is pleased to credit your account with $10.00 in birthday credits. You can spend these credits on anything in our online store, but there's a catch! They will expire in a week if you do not use them! So wait no further and go to your personalized web page at:

 

http://www.XYZWeb.com/bday/home/home.html/782-3339950-1258814

 

Now that you are 18, you can finally do what you have been waiting for all your life - sign up for your very own XYZweb online cash management account! We are waiving the first year's fee if you apply within the next 2 weeks! Apply now at:

 

http://www.XYZWeb.com/bday/1234&=18badgrz

 

Did you know that you can access XYZweb's store directly from AOL? Click on keyword XYZWeb and land on your personalized page.

The resulting message to a person from Texas and randomly selected would read:

Figure 133 Resulting Recipient Plain Text Message

Happy birthday!

 

To celebrate the occasion, XYZweb is pleased to credit your account with $10.00 in birthday credits. You can spend these credits on anything in our online store, but there's a catch! They will expire in a week if you do not use them! So wait no further and go to your personalized web page at:

 

http://www.XYZWeb.com/bday/home/home.html/104-1119951-0252744

 

Congratulations! You have won a free pair of XYZweb sunglasses!