Setting Up and Sending E-mail for Campaigns

 

Campaign Manager for WebLogic provides a default Mail Service, based on JavaMail, to process e-mail requests from scenario actions.

This topic includes the following sections:

• How Campaigns Use the Mail Service

• Setting Properties for the Mail Service

• Creating E-mail JSPs

• Sending Bulk Mail

Instead of the Campaign Manager for WebLogic Mail Service, you can use a third-party mail service.

 

---

How Campaigns Use the Mail Service

Business Analysts (BAs) can specify that a scenario within a campaign sends an e-mail to a customer. For example, when a customer buys a flashlight, a scenario can send a an e-mail that contains special offers for batteries.

When BAs create scenarios, they provide the URI of a JSP file that contains the e-mail content. When a customer triggers the scenario action, the following process occurs:

1. The Campaign Service uses HTTP to request the JSP URI that the scenario action specifies. In the request, it passes parameters to identify the name of the scenario and the identity of the customer who triggered the scenario action.

2. The JSP invokes any JSP tags that it contains, uses MIME types to encode non-ASCII output, and stores its output in the Campaign Manager for WebLogic data repository. The data repository organizes the e-mails into batches; one batch for each campaign.

3. You issue a command to the Mail Service that specifies which batch of messages you want to send. The Mail Service uses the JavaMail API to send the messages.

   Figure 4-1 The Mail Service for Campaigns

   
    

 

---

Setting Properties for the Mail Service

Before a campaign can send e-mail, you must set properties for the Mail Service. In a clustered domain, you must set these properties on each machine in the cluster.

To set properties, do the following:

1. Open the Administration Tool and find the following:

   • The name of the property set and the property that defines customer e-mail addresses.

   • The name of the property set and the property that records a customer's preference for receiving campaign-related e-mail. By default, this information is stored in the Demographics property set in the Email_Opt_In property.

     For information about property sets and properties, refer to "Creating and Managing Property Sets" in the Guide to Building Personalized Applications.

2. From a text editor, open the following file:

   WL_COMMERCE_HOME/weblogiccommerce.properties

   where WL_COMMERCE_HOME is the directory in which you installed Campaign Manager for WebLogic.

3. In weblogiccommerce.properties, find the section that begins with the following line (see Listing 4-1):
   # MailService and MailAction properties

4. Enter values for the following properties:

   • mail.smtpHost. Enter the name of the SMTP host (the server that sends e-mail).

   • mailAction.defaultFromAddress. Enter the default address that receives any replies from e-mail that the campaign sends. In a standard mail header, this is the From address.

     Each campaign scenario can specify its own From address. A scenario-provided From address overrides this mailAction.defaultFromAddress property.

   • mailAction.emailPropertySet. Enter the name of the property set that contains customer e-mail properties.

   • mailAction.emailPropertyName. Enter the name of the property that contains customer e-mail addresses.

5. By default, the Mail Service directs requests to localhost. However a clustered environment uses a single proxy server to accept HTTP requests (including HTTP requests from the Mail Service). In a clustered environment, you must specify the name and port number of the proxy server by removing the comment characters from the following properties and entering values that are appropriate for your environment:

   • mailAction.jspHost. Enter the name of the cluster's proxy server.

   • mailAction.jspPort. Enter the port to use when connecting to the host that you specified in mailAction.jspHost.

6. If you use a different property set and property to record customer's campaign-related e-mail preferences, modify the values of mailAction.optInPropertySet and mailAction.optInPropertyName.

   Listing 4-1 Mail Properties in weblogiccommerce.properties

   ###############################################

   # MailService and MailAction properties

   # SMTP Host for the MailService to use
   mail.smtpHost=walawala.sprockets.com

   # A default from-address, if none is provided to the MailAction
   mailAction.defaultFromAddress=[e-mail]

   # The property set to query for the user's email address
   mailAction.emailPropertySet=Customer Properties

   # The name of the property to query for the user's email address
   mailAction.emailPropertyName=email

   # The property set that contains the email opt-in property
   mailAction.optInPropertySet=Demographics

   # The name of the email opt-in property. If a user sets this to
   # false, MailAction will not send any emails to that user.
   mailAction.optInPropertyName=Email_Opt_In

   # The name of the server that contains the email-generating JSP's
   # (overriding this should only be necessary in a cluster)
   #mailAction.jspHost=localhost

   # The port of the server that contains the email-generating JSP's
   # (overriding this should only be necessary in a cluster)
   #mailAction.jspPort=7501

7. Save your modifications to weblogiccommerce.properties.

8. To use the modified properties, restart the server. The server only refers to its properties file during the startup process.

 

---

Creating E-mail JSPs

The E-mail Service requires that you place the content and formatting of your e-mails in a JSP file. In this JSP, you can use any of the JSP tags and APIs that are available to other JSPs in Campaign Manager for WebLogic.

You must save the JSP on your Campaign Manager for WebLogic host in a location that Campaign Manager for WebLogic processes can access.

This section describes the following:

• E-mail Parameters

• Sample E-mail JSP

E-mail Parameters

When a scenario action requests an e-mail JSP, it passes a userId parameter, which specifies the login name of the customer who triggered the scenario action. With the request.getParameter method, you can retrieve the user ID and pass it to JSP tags in the e-mail JSP.

In addition, the scenario passes the following parameters (you can also pass these parameters to JSP tags in the e-mail JSP):

• scenarioId, which specifies the ID of the scenario that triggered the e-mail.

• scenarioName, which specifies the name of the scenario that triggered the e-mail.

• containerId, which specifies the ID of the campaign to which the scenario belongs.

• containerName, which specifies the name of the campaign to which the scenario belongs.

Sample E-mail JSP

Listing 4-2 shows an example of an e-mail JSP, which does the following:

• Imports the user management tag library (um.tld).

• Uses request.getParameter object to retrieve the contents of the userId parameter.

• Passes the userId to the <um:getProfile> JSP tag to get the user's profile.

• Uses the <um:getProperty> to display the user's first and last name, and the user's home city and state.

  Listing 4-2 Sample E-mail JSP

  <%@ taglib uri="um.tld" prefix="um" %> 

  <%
    String userId = (String)request.getParameter( "userId" );
    if ( userId == null )
    {
      throw new ServletException( "A userId is required to generate this email" );
    }
  %> 

  <um:getProfile profileKey="<%= userId %>" /> 

  Dear 
  <um:getProperty propertyName="FirstName"/>
  <um:getProperty propertyName="LastName"/>, 

  Thank you for shopping at our store! We noticed that you are from

  <um:getProperty propertyName="contactAddressCity"/>, 
  <um:getProperty propertyName="contactAddressState"/>, 

  and thought you would be interested in purchasing tickets to the Yankees-Red Sox game...

 

---

Sending Bulk Mail

You must periodically use a command to send the batches e-mail that the JSPs store in the Campaign Manager for WebLogic data repository. You can also use cron or any other scheduler that your operating system supports to issue the send-mail command.

On Windows, the send-mail command is in a .bat file wrapper script; on UNIX it is in a .sh file. This section refers to the .bat file. UNIX users should substitute .sh for .bat.

This section includes the following subsections:

• Sending Mail from a Remote Host or in a Clustered Environment

• To Send Bulk E-mail

• To Delete E-mail Batches

• Scheduling Bulk E-mail Delivery

• MailManager Command Reference

Sending Mail from a Remote Host or in a Clustered Environment

The send-mail wrapper script specifies the name and listen port of the Campaign Manager for WebLogic host that processes the send-mail request. By default, the wrapper script specifies localhost:7501 for the hostname and listen port. However, localhost:7501 is valid only when you run the script while logged in to a Campaign Manager for WebLogic host in a single-node environment (and only if you did not modify the default listen port).

Before you use the send-mail script from any other configuration, you must modify the script. This section describes the following tasks:

• Modifying the Send-Mail Script to Work from a Remote Host

• Modifying the Send-Mail Script to Work in a Clustered Environment

Modifying the Send-Mail Script to Work from a Remote Host

If you want to run the send-mail script from a remote host (that is, a computer that is not a Campaign Manager for WebLogic host), do the following:

1. Open the following file in a text editor:
   WL_COMMERCE_HOME\bin\win32\mailmanager.bat (Windows)
   WL_COMMERCE_HOME/bin/win32/mailmanager.sh (UNIX)

2. In the mailmanager script, in the SET HOST= line, replace localhost with the name of a Campaign Manager for WebLogic host.

3. If the host uses a listen port other than 7501, in the SET PORT= line, replace 7501 with the correct listen port.

4. Save the mailmanager script.

Modifying the Send-Mail Script to Work in a Clustered Environment

If you work in a clustered environment, you must modify the send-mail wrapper script to specify the name of a host in the cluster. The default localhost value is not valid for the Mail Service in a clustered environment.

To use the send-mail script in a clustered environment, do the following on each host from which you want to run the script:

1. Open the following file in a text editor:
   WL_COMMERCE_HOME\bin\win32\mailmanager.bat (Windows)
   WL_COMMERCE_HOME/bin/win32/mailmanager.sh (UNIX)

2. In the mailmanager script, in the SET HOST= line, replace localhost with the name of a Campaign Manager for WebLogic host. Because each host in a cluster can access the data repository that stores the e-mail messages, you can specify the name of any host in the cluster.

3. If the host uses a listen port other than 7501, in the SET PORT= line, replace 7501 with the correct listen port.

4. Save the mailmanager script.

To Send Bulk E-mail

To send bulk e-mail, do the following from a shell that is logged in to a Campaign Manager for WebLogic host:

1. To determine the names and contents of the e-mail batches in the data repository, enter the following command:

   MailManager.bat list (Windows)

   The command prints to standard out. You can use shell commands to direct the output to files.

2. To send a batch and remove it from the data repository, enter the following command:

   MailManager.bat send-delete batch-name

To Delete E-mail Batches

You can delete e-mail batches as you send them (as described in To Send Bulk E-mail). You can also do the following to delete e-mail batches:

1. To determine the names and contents of the e-mail batches in the data repository, enter the following command:

   MailManager.bat list

   The command prints to standard out. You can use shell commands to direct the output to files.

2. To delete a batch, enter the following command:

   MailManager.bat delete batch-name

Scheduling Bulk E-mail Delivery

You can use a scheduling utility to send the e-mail batches in the data repository. Because you must specify the name of a batch when you use the MailManager command to send mail, you must schedule sending mail for each campaign scenario separately. The name of a batch corresponds to the scenario's container ID. For information about the container ID, refer to E-mail Parameters.

For information in using a scheduling utility, refer to the documentation for your operating system.

MailManager Command Reference

The MailManager command is a wrapper script that uses java.com.bea.commerce.platform.mail.MailManager.

The command syntax is as follows:

MailManager.bat [ list | send | send-delete | delete ] [ batch-name ] (Windows)

MailManager.sh [ list | send | send-delete | delete ] [ batch-name ] (UNIX)

If you do not specify command arguments, MailManager prints to standard output the names all e-mail batches in the data repository and the number of e-mails in each batch.

Use the command arguments as follows:

• list

  Prints to standard output the names of all e-mail batches in the data repository and the number of e-mails in each batch.

• list batch-name

  Prints to standard output the subject and recipients of all e-mail in the batch that you specify.

• send batch-name

  Sends all e-mails in the batch that you specify.

• send-delete batch-name

  Sends all e-mails in the batch that you specify and then deletes the batch from the data repository.

• delete batch-name

  Deletes e-mails in the batch that you specify.

• batch-name

  The name of a batch that MailManager list returns. This argument does not support wildcards.

Command Examples

To list all available batches, enter the following command:
MailManager.bat list

To list the contents of a batch named campaign1, enter the following command:
MailManager.bat list campaign1

To send the campaign1 batch and delete it afterwards, enter the following command:
MailManager.bat send-delete campaign1

To delete the campaign1 batch, enter the following command:
MailManager.bat delete campaign1