Setting Up and Sending E-mail for Campaigns

 

WebLogic Portal 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

• Configuring E-Mail Properties for Campaigns

• Creating E-mail JSPs

• Sending Bulk Mail

Instead of the WebLogic Portal 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 select 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 internal 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 WebLogic Portal 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

   
    

 

---

Configuring E-Mail Properties for Campaigns

Before a campaign can send e-mail, you must configure properties that the Campaign Service uses to send and receive mail. In a clustered environment, WebLogic Server propagates these properties to each node in the cluster.

To configure mail-related properties, do the following:

1. From the E-Business Control Center, open your application.

2. In the E-Business Control Center Explorer window, click the Site Infrastructure tab.

3. Click User Profiles and find the following (see Figure 4-2):

   • 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. The reference applications store this preference 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.

     Figure 4-2 Find Names of User Properties

     
      

4. Start your server and access the WebLogic Server Administration Console for the domain. For more information, refer to "The WebLogic Server Administration Console" in the WebLogic Portal Architectural Overview.

5. In the left pane of the WebLogic Server Administration Console, click Deployments -> Applications -> myApplication -> Service Configuration -> Campaign Service.

6. On the Campaign Service Page, click the Mail Action tab.

7. On the Mail Action tab, enter the following values:

   In this box...	Enter this value...
   Default From Email Address	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 that overrides this default property.
   Email Address Property Name	The name of the property that contains customer e-mail addresses.
   Property Set Name Containing Email Address Property	The name of the property set that contains customer e-mail properties.
   Email Opt In Property Name	The name of the property that specifies whether customers want to receive campaign-related email. The reference applications store this preference in the Demographics property set in the Email_Opt_In property.
   Property Set Name Containing Opt In Property	The name of the property set that contains the customer's opt-in property.

8. Click Apply. All e-mail that the Campaign Service generates will now use these settings.

9. To configure the default SMTP host name for the Mail Service, in the left pane, click Mail Service. Any changes that you make on the Mail Service page affects all e-mails (whether or not they are generated by the Campaign Service) that you send using WebLogic Portal.

 

---

Creating E-mail JSPs

The 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 WebLogic Portal.

This section describes the following:

• E-mail Parameters

• Disabling Session Generation

• Sample E-mail JSP

• Location of E-Mail JSPs

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.

Disabling Session Generation

The Java class that the Campaign Service uses to generate email from a JSP, InternalRequestDispatcher, also generates an HTTPSession object. Usually, generating this HTTPSession from an email JSP is extraneous because your application already generates an HTTPSession object when a customer accesses your site.

To disable the generation of an extraneous HTTPSession, add the following directive to the beginning of the JSPs that you use to generate email for campaigns:

<%@ page session="false" %>

Adding this directive is necessary only if your application generates HTTPSession objects when customers access your site (or log in) and only for email that is generated via the InternalRequestDispatcher.

Sample E-mail JSP

Listing 4-1 shows the e-mail JSP that is part of the wlcs sample Web application. The file is located at PORTAL_HOME/applications/wlcsApp/wlcs/campaigns/emails/Sample1.jsp

Listing 4-1 Sample E-mail JSP

<%@ page session="false" %>

<%@ page contentType="text/plain" %>

(This sample e-mail was automatically sent out as part of a sample campaign that you triggered while registering as a new user on the BEA Commerce Templates.)

-------------------------------

Hello <%= request.getParameter("userId") %>,

Thank you for taking the time to become a registered member of our site. We hope you took advantage of your $10 discount on a purchase of $50 or more after you registered!

In addition, your registration entitles you to premium services including:

	**Special "Members Only" discounts
	**Advance notice of new product releases
	**A personalized customer experience customized to your
          specific interests

Thanks again for becoming a registered member.

Best Regards

Location of E-Mail JSPs

You must save e-mail JSPs in a specific directory within a Web application so that BAs can use the E-Business Control Center to browse and select the e-mail for a campaign.

By default, the directory is myApp/myWebApp/campaigns/emails.

For example, the wlcs application provides a sample e-mail in the following directory:
PORTAL_HOME/applications/wlcsApp/wlcs/campaigns/emails/
Sample1.jsp

To choose this e-mail as part of a scenario action, a BA opens the wlcsApp application in the E-Business Control Center. Then, while creating an E-mail action, the BA can browse through all e-mail JSPs that have been saved in PORTAL_HOME/applications/wlcsApp/wlcs/campaigns/emails and select Sample1.jsp for the scenario.

To change the default location in which you save JSP e-mail, do the following:

1. From the WebLogic Server Administration Console, in the left pane, click Deployments -> Applications -> myApplication -> Service Configuration-> Campaign Service.

2. On the Campaign Service page, click the Configuration tab.

3. In the Base Directory for Email Browsing box, enter a pathname that is relative to the root directory of a Web application.

 

---

Sending Bulk Mail

You must periodically use a command to send the batches e-mail that the JSPs store in the WebLogic Portal 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 WebLogic Portal 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 WebLogic Portal 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 WebLogic Portal host), do the following:

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

2. In the mailmanager script, in the SET HOST= line, replace localhost with the name of a WebLogic Portal 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:
   PORTAL_HOME\bin\win32\mailmanager.bat (Windows)
   PORTAL_HOME/bin/unix/mailmanager.sh (UNIX)

2. In the mailmanager script, in the SET HOST= line, replace localhost with the name of a WebLogic Portal 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 WebLogic Portal host:

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

   mailmanager.bat appName list (Windows)

   where appName is the name of the enterprise application that generated the e-mail batch. (See Figure 4-3.) 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 appName send-delete batch-name

   Figure 4-3 Application 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 appName list

   where appName is the name of the enterprise application that generated the e-mail batch. (See Figure 4-3.) 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 appName 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.p13n.mail.MailManager. The command syntax is as follows:

mailmanager.bat [ appName ] [ list | send | send-delete | delete ] [ batch-name ] (mailmanager.sh on UNIX)

If you specify only the appName arguments mailmanager prints to standard output the names all e-mail batches in the application and the number of e-mails in each batch.

Use the command arguments as follows:

• appName

  The name of the enterprise application that generated the e-mail batch.
  (See Figure 4-3.)

• 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 /campaigns/campaign1.cam that the wlcsApp application generated, enter the following command:
mailmanager.bat wlcsApp list /campaigns/campaign1.cam

To send the campaign1.cam batch and delete it afterwards, enter the following command:
mailmanager.bat wlcsApp send-delete /campaigns/campaign1.cam

To delete the campaign1.cam batch, enter the following command:
mailmanager.bat wlcsApp delete /campaigns/campaign1.cam