Setting Up Campaign Services

A campaign coordinates several WebLogic Portal services to create and track marketing goals on an e-commerce Web site. For example, your marketing organization can use campaigns to sell 100 ACME saws during the month of June. To reach this goal, Marketing can target advertising, e-mail, and discounted product pricing to customers who match a set of criteria, such as customers who have previously purchased ACME hardware from your site.

Your responsibility in setting up a campaign service is to develop the infrastructure to support the campaigns and modify that infrastructure as individual campaigns require. This activity can include building placeholders for campaigns, specifying display and clickthrough behavior, loading ads into a content management system, creating personalized e-mails for campaigns, and sending bulk mail to prospective and existing customers.

This section contains information on the following subjects:

• What are Campaign Services?

• Building Placeholders for Campaigns

• Using Attributes to Specify Display and Clickthrough Behavior

• Loading Ads Into Your Content Management System

• Creating Personalized E-mails for Campaigns

• Sending Bulk Mail

Note: Campaigns cannot be used with anonymous users.

 

---

What are Campaign Services?

Campaigns coordinate the following services:

• Events and Behavior Tracking services identify how a customer interacts with your site. By default WebLogic Portal tracks only a specific set of customer interactions (events), but you can add to this set by customizing the Event Service. For more information on event and behavior tracking, see Event and Behavior Tracking.

• Customer Segments categorize customers based on information in a customer's profile and other dynamic data. Each customer must create a profile to log in to your site. The profile includes information that the customer provides, such as shipping addresses, and information that WebLogic Portal provides, such as number of visits and total value of products the customer has purchased on the site. You can create customer segments in the E-Business Control Center.

• Scenarios which trigger actions if a specific event occurs or if a specific customer matches a customer segment. You can create scenarios in the E-Business Control Center.

Scenarios can engage any of the following services:

• Ad Placeholders, which query the content management system for an ad and display the query results on the Web site. For example, if a customer logs in and the customer's profile matches the SailingEnthusiast customer segment, then a scenario causes an ad for sailboats to appear in the Web site's top banner.

• E-mail Service, which uses a JSP to generate e-mail and provides a utility for sending the e-mail in batches. Because the Mail Service uses a JSP to generate e-mail, you can use JSP tags to personalize the e-mail.

Discounts These offer reduced prices for specific products or product categories. You can creates discount in the E-Business Control Center.

 

---

Building Placeholders for Campaigns

The ad placeholder is a container that generates the HTML that the browser requires to display the ad content and places it in the JSP at the location of the placeholder tag. An ad is a document in your content management system that an ad placeholder displays. Ads can be an integral part to a campaign. For example, campaigns can specify as a goal to record a specific number of ad clickthroughs.

 

---

Using Attributes to Specify Display and Clickthrough Behavior

You need to define the document attributes in your content management system that ad placeholders use to support the following features:

• Choosing a single document if a query returns multiple documents

• Making an image ad clickable

• Supplying movie preferences for a Shockwave file

For information about associating attributes with documents, refer to the documentation for your content management system. If you use the reference content management system supplied by BEA, refer to Loading Ads into the Reference Content Management System. Valid attributes are listed in Table  13-1, Table  13-2, and Table  13-3.

 

---

Loading Ads Into Your Content Management System

The queries you can define for ad placeholders search through the attributes that you attach to the documents in your content management system. WebLogic Portal places no restrictions on the set of attributes that you use to describe your ads. For example, you can create attributes that describe the name of the product that the document advertises, the name of the ad sponsor, and a product category that matches the categories in your e-commerce product catalog.

The method of loading ads into a content management system is dictated by the CMS.

• If you use the reference content management system supplied by BEA, use the procedures in this section.

• If you are using a third-party CMS, follow the load instructions provided by the vendor.

Loading Ads into the Reference Content Management System

WebLogic Portal provides a content management system for sites with limited content-management needs. If you use the reference content management system, you must load ads and ad attributes at the same time. You cannot add attributes to documents that have already been loaded.

When you install WebLogic Portal, the reference content management system (which uses the sample PointBase database) already contains a set of sample ads.

To load ads and ad attributes into the reference content management system, you must do the following:

• Step 1. Set Up Attributes in HTML Documents

• Step 2. Set Up Attribute Files for Image and Shockwave Documents

• Step 3. Move Files Into the dmsBase/Ads Directory Tree

• Step 4. Run the loadads Script

Step 1. Set Up Attributes in HTML Documents

For ads that contain only HTML, you must place document attributes in <META> tags within a document's <HEAD> element. Use the following syntax in the <META> tag:

<META name="attribute-name" content="attribute-value">

Use a separate <META> tag for each document attribute. For example:

<META name="attribute1-name" content="attribute1-value">
<META name="attribute2-name" content="attribute2-value">
<META name="attribute3-name" content="attribute3-value">

Listing  13-1 shows an HTML file that contains a simple ad with several attributes.

Listing 13-1 Attributes for an HTML Ad

<HTML>
<HEAD>

<META name="adWeight" content="3"> 
<META name="productCategory" content="hardware"> 
<META name="productSubCategory" content="electic drill"> 
<META name="productName" content="Super Drill"> 
<META name="Manufacturer" content="ACME"> 

</HEAD>

<BODY>

<P>Buy our Super Drill. It'll get the job done!</P>

</BODY>

</HTML>

Table  13-1 describes the adWeight attribute, which you can associate with XHTML, image, and Shockwave documents.

Table 13-1 Attributes for All Document Types

Attribute Name	Value Type	Description and Recommendations
adWeight	Integer	Provides an integer that is used to select a document if a query returns multiple documents. Assign a high number to ads that you want to have a greater chance of being selected. The default value for this attribute is 1. Note: In the E-Business Control Center, you can assign a priority to a query for a scenario action. The priority, which bears no relation to the adWeight attribute, gives a greater or lesser chance that a placeholder runs a query. The adWeight attribute is used to choose an ad after a query has run.

 

Step 2. Set Up Attribute Files for Image and Shockwave Documents

For ads that are images or Shockwave movies, you must place attributes in a separate file. Each image or Shockwave file must be accompanied by a separate file that is named with the following convention:

filename.extension.md.properties

Both files must be located in the same directory.

For example, for an image file named superDrill.jpg, you must place attributes in a file named superDrill.jpg.md.properties.

Within the filename.extension.md.properties file, use the following syntax to express attributes and values:

attribute-name=attribute-value

Listing  13-2 shows an example file that contains attributes for an image ad.

Listing 13-2 Syntax for the Attributes File

adWeight=5 
adTargetUrl=AcmeAds/saws.jpg 
adAltText=Buy ACME and save!

productCategory=hardware
productSubCategory=electic drill
productName=Super Drill
Manufacturer=ACME

Other Image File Attributes

Table  13-2 describes other attributes, in addition to adWeight, that you can associate with image files.

Table 13-2 Attributes for Image Files  

Attribute Name	Value Type	Description and Recommendations
adTargetUrl	String	Makes an image clickable and provides a target for the clickthrough, expressed as a URL. The Event Service records the clickthrough. Use either adTargetUrl, adTargetContent, or adMapName, depending on how you want to identify the destination of the ad clickthrough.
adTargetContent	String	Makes an image clickable and provides a target for the clickthrough, expressed as the content management system's content ID. The Event Service records the clickthrough. Use either adTargetUrl, adTargetContent, or adMapName, depending on how you want to identify the destination of the ad clickthrough.
adMapName	String	Makes an image clickable, using an image map to specify one or more targets. The value for this attribute is used in two locations: In the anchor tag that makes the image clickable, <a href=value> <img> </a> In the map definition, <map name=value> Use either adTargetUrl, adTargetContent, or adMapName, depending on how you want to identify the destination of the ad clickthrough. If you specify a value for adMapName, you must also specify a value for adMap.
adMap	String	Supplies the XHTML definition of an image map. If you specify a value for adMap, you must also specify a value for adMapName.
adWinTarget	String	Displays the target in a new pop-up window, using JavaScript to define the pop-up. The only value supported for this attribute is newwindow.
adWinClose	String	Specifies the name of a link that closes a pop-up window. The link appears at the end of the window content. For example, if you provide "Close this window" as the value for this attribute, then "Close this window" appears as a hyperlink in the last line of the pop-up window. If a customer clicks the link, the window closes.
adAltText	String	Specifies a text string for the alt attribute of the <img> tag. If you do not include this attribute, the <img> tag does not specify an alt attribute.
adBorder	Integer	Specifies the value for the border attribute of the <img> tag. If you do not include this attribute, the border attribute is given a value of "0".

 

Other Shockwave Attributes

Table  13-3 describes other attributes, in addition to adWeight, that you can associate with Shockwave files. Ad placeholders and the <ad:adTarget> tag format these values as attributes of the <OBJECT> tag, which Internet Explorer on Windows uses to display the file, and the <EMBED> tag, which browsers that support the Netscape-compatible plug-in use to display the file.

For more information about these attributes, refer to your Shockwave developer documentation.

Table 13-3 Attributes for Shockwave Files  

Attribute Name	Value Type	Description and Recommendations
swfLoop	String	Specifies whether the movie repeats indefinitely (true) or stops when it reaches the last frame (false). Valid values are true or false. If you do not define this attribute, the default value is true.
swfQuality	String	Determines the quality of visual image. Lower qualities can result in faster playback times, depending on the client's Internet connection. Valid values are low, high, autolow, autohigh, best.
swfPlay	String	Specifies whether the movie begins playing immediately on loading in the browser. Valid values are true or false. If you do not define this attribute, the default value is true.
swfBGColor	String	Specifies the background color of the movie. This attribute does not affect the background color of the HTML page. Valid value syntax is #RRGGBB.
swfScale	String	Determines the dimensions of the movie in relation to the area that the HTML page defines for the movie. Valid values are showall, noborder, exact fit.
swfAlign	String	Determines whether the movie aligns with the center, left, top, right, or bottom of the browser window. If you do not specify a value, the movie is aligned in the center of the browser. Valid values are l, t, r, b.
swfSAlign	String	Determines the movie's alignment in relation to the browser window. Valid values are l, t, r, b, tl, tr, bl, br.
swfBase	String	Specifies the directory or URL used to resolve relative pathnames in the movie. Valid values are .(period), directory-name, URL.
swfMenu	String	Determines whether the movie player displays the full menu. Valid values are true or false.

 

Step 3. Move Files Into the dmsBase/Ads Directory Tree

To make the ads available to the campaign, place all HTML, image, and Shockwave files, and all attributes files into the Ads directory, which is located at the following path:

<BEA_HOME>/user_projects/<YOUR-APPLICATIONDOMAIN>/dmsBase/Ads 

(where <BEA_HOME> is the directory in which you installed BEA WebLogic Platform and where <YOUR-APPLICATIONDOMAIN> is the directory of the particular domain).

You can place documents in subdirectories of the Ads directory, although the reference content management system does not use the subdirectories to organize documents.

If you use subdirectories to manage your source files, you must place the attributes files in the same directory as the files that they describe. For example, superDrill.jpg and superDrill.jpg.md.properties must be in the same directory.

Step 4. Run the loadads Script

The loadads script (loadad.bat for Windows user; loadad.sh for Unix users) runs the BulkLoader to load documents from the dmsBase/Ads directory to the content management system. It also attaches attributes to the documents.

To run loadads, do one of the following:

• Type loadads at the command line (or Start -\> Run in Windows NT or 2000). Be sure you are in the <BEA_HOME>/user_projects/ <YOUR-APPLICATIONDOMAIN>/dmsBase directory.

OR

• Open Windows Explorer, locate loadads in the <BEA_HOME>/user_projects/<YOUR-APPLICATIONDOMAIN>/dmsBase directory, and double-click it in the file list.

For more information on running the BulkLoader, please see Adding Content by Using the Bulk Loader.

 

---

Creating Personalized E-mails for Campaigns

The E-mail service uses a JSP to generate e-mail and provides a utility for sending the e-mail in batches. Because the Mail service uses a JSP to generate e-mail, you can use JSP tags to personalize the e-mail. This section shows you how to create personalized e-mails for campaigns by following these steps:

• Step 1. Configure the E-mail Properties

• Step 2. Find Names of User Properties

• Step 3. Create E-mail JSPs

Step 1. Configure the E-mail Properties

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:

   • 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.

Step 2. Find Names of User Properties

1. Start your server and access the WebLogic Server Administration Console for the domain.

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

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

4. On the Mail Action tab, enter the following values.

   Table 13-4 Mail Action Tab 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.

   
    

5. Click Apply.

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

6. Configure the default SMTP host name for the Mail Service by clicking Mail Service in the left pane.

   Note: Any changes that you make on the Mail Service page affects all e-mails that you send using WebLogic Portal (whether or not they are generated by the Campaign Service).

Step 3. Create 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 step describes the following:

• E-mail Parameters

• Disabling Session Generation

• Sample E-mail JSP

• Saving 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. By using 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  13-3 shows the e-mail JSP that is part of the sample Web application. The file is located at <BEA_HOME>/weblogic700/samples/portal/ wlcsDomain/beaApps/wlcsApp/wlcs/campaigns/emails/

Listing 13-3 Sample E-mail JSP

Sample1.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

Saving E-Mail JSPs

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

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

(Where myWebApp is the name of a Web application containing the campaign)

For example, the Web application wlcs provides a sample e-mail in the following directory:

<BEA_HOME>/weblogic700/samples/portal/wlcsDomain/beaApps/wlcsApp/
   wlcs/campaigns/emails/Sample1.jsp

To choose this e-mail as part of a scenario action, do the following:

1. Open the wlcsApp application in the E-Business Control Center.

2. While creating an E-mail action, to browse through all e-mail JSPs that have been saved in <BEA_HOME>/weblogic700/samples/portal/wlcsDomain/ beaApps/wlcsApp/wlcs/campaigns/emails and select Sample1.jsp for the scenario.

To change the default location in which you save e-mail JSPs, 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 batched 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.

This section includes information on the following subsections:

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

• Sending Bulk E-mail

• Scheduling Bulk E-mail Delivery

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 by doing one of the following tasks:

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

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

Modify 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:

   <BEA_HOME>\weblogic700\portal\bin\win32\mailmanager.bat (Windows)

   <BEA_HOME>\weblogic700\portal\bin\win32\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.

Modify 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:

   <BEA_HOME>\weblogic700\portal\bin\win32\mailmanager.bat (Windows)

   <BEA_HOME>\weblogic700\portal\bin\win32\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.

Sending 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)

   mailmanager.sh appName list (Unix)

   where appName is the name of the enterprise application that generated the e-mail batch. 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 (Windows)

   mailmanager.sh appName send-delete batch-name (Unix)

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.

Deleting E-mail Batches

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

1. Determine the names and contents of the e-mail batches in the data repository by entering the following command:

   mailmanager.bat appName list (Windows)

   mailmanager.sh appName list (Unix)

   where appName is the name of the enterprise application that generated the e-mail batch. The command prints to standard out. You can use shell commands to direct the output to files.

2. Delete a batch by entering the following command:

   mailmanager.bat appName delete batch-name (Windows)

   mailmanager.bat appName delete batch-name (Unix)