Interaction Management Guide
Campaigns are powerful tools for personalization, letting you target users with specific Web content, e-mails, and discounts based on specific conditions and fine-grained rules.
The following topics guide you through the campaign creation process:
Campaigns let you provide the following for individual users:
Campaigns are extremely flexible, because they let you create business logic without requiring code changes. For example, campaigns show Web content using a JSP tag called a placeholder that looks like this: <ph:placeholder name="myPlaceholder1"/>
. Add JSP placeholder tags (uniquely identified by the "name" attribute) anywhere you want in your portal's JSPs. Then simply define your campaigns to use the existing placeholders, each of which can display content unique to the campaign and to the individual users. Campaigns can change and be added, but you never have to change your JSP code. The placeholders you need stay the same.
In addition to providing this high level of flexibility and personalization, campaigns, as the name implies, begin at a specific time and end when their purpose has been fulfilled, whether specific goals have been achieved or a time deadline has been reached. Campaigns can even be set up to run only once for each visitor.
Structurally, a campaign contains one or more scenarios, and each scenario contains one or more actions that show personalized content, send an automatic e-mail, and/or provide a personalized discount. The advantage of scenarios as containers for actions is that you can use user segments to determine which users are eligible to be targeted with the actions in a scenario (though you are not required to assign user segments to scenarios). For example, you could create a campaign with two scenarios: One that will target its actions only to males and the other that will target its actions only to females. The logic would work like this in a scenario for females:
The following scenarios provide examples of the versatility and power provided by campaigns:
Campaigns and behavior tracking are not currently supported for anonymous, non-trackable users. See "Anonymous Users" in the User Management Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/users/anonymous.html.
Campaign scenario rules are evaluated only when a single event occurs for which the campaign service is listening.
Note: By default, the only events that do not trigger campaigns are DisplayContentEvent, DisplayProductEvent, BuyEvent, SessionBeginEvent, and SessionEndEvent, as listed in <PortalApplication>/wps.jar/com/bea/campaign/internal/listeners.properties
.)
If your campaign conditions use request, session, or event properties, those properties are captured when a listened-for event is triggered. The event takes a snapshot of the current session properties, the single request property (contained in the session), and the event properties (contained in the request). The snapshot taken by the event is in the form of a request object, which the event passes to the campaign service for evaluation. If the values in that snapshot evaluate to true against any campaign action rules, those campaign actions are triggered.
When campaign actions are not triggered as expected using session, request, and event properties, one or more of the following is usually to blame:
Consider the following Campaign action rules as created in WebLogic Workshop:
The rule will be evaluated only if an event for which the campaign service is listening occurs. (This event need not be used directly in the campaign rule.) For example, if the campaign service is configured to listen for the BEA-provided UserRegistrationEvent (which it is by default), then when a UserRegistrationEvent occurs the event takes a snapshot of the Request object and the Campaign rules are evaluated.
Here is how the previous Campaign action rules would be evaluated:
Because a UserRegistrationEvent woke up the campaign service and took a snapshot of the request object, the campaign action will not be triggered, because the rule requires that all of its conditions evaluate to true. The SessionLoginEvent rule is false (because it was the UserRegistrationEvent that woke up the campaign service).
If the rule was defined differently so that any of the conditions evaluating to true would trigger the action (rather than all conditions), the campaign action would have fired if the request property evaluated to true.
Note: If you are using e-mails in your Campaign, you can choose to send the e-mails in batch mode or real-time (batch mode is the default). In batch mode, when you run or test your Campaign, no e-mails will be sent. See Setting Up Bulk E-Mail Messages to learn how to send batch mode emails. See Creating Campaigns for instructions on how to change the mailing behavior to real-time.
Before you create campaigns, ensure that you have performed the following appropriate steps.
Note: Campaigns and behavior tracking are not currently supported for anonymous, non-trackable users. See "Anonymous Users" in the BEA WebLogic User Management Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/users/anonymous.html.
See Creating a Portal Application and Portal Web Project in the WebLogic Workshop help system.
When you show personalized content with a campaign (using a content rule), the content is retrieved from BEA's Virtual Content Repository and displayed in a placeholder. There are many properties you can add to your content that enable necessary and helpful features for campaigns. For example, to increase the chances of a specific content item being shown in a placeholder, create an adWeight
property (as an Integer) for your content items. The greater the adWeight
number you enter for a content item, the greater the chances that it will be displayed in a placeholder if it is retrieved by a query.
For more information on setting up content for use in interaction management, see Setting up Content in this guide.
For instructions on using content management in WebLogic Portal, choose from the list of Content Management topics on the e-docs home page at http://download.oracle.com/docs/cd/E13218_01/wlp/docs81/index.html.
If you are using Goal Setting in campaigns to end a campaign based on the number of content items displayed and/or clicked:
Campaigns use placeholders to display personalized Web content. If you will display personalized content through campaigns, create the placeholders that will hold your campaign queries and display the Web content.
For more information on placeholders, see Placeholders in this guide. In particular, see the section on "Combining Default Queries and Campaign Queries in Placeholders."
If you want to trigger campaign scenarios based on users who are grouped dynamically based on specific characteristics, create user segments. For more information on user segments, see the Interaction Management Overview in this guide and "Creating User Segments" in the WebLogic Workshop help system at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/buildportals/CreatingSegments.html.
If you will trigger campaigns based on user, event, HTTP session, or HTTP request properties, perform any of the following relevant procedures found in the WebLogic Workshop help system:
For more information on how these properties are used in interaction management, see the Interaction Management Overview in this guide.
If you will send automatic e-mails in campaigns, make sure you have done the following:
Email
property that can contain a single, unrestricted String value for an e-mail address.You can also tell the campaign service to send automatic e-mails only if users have specified that they want to receive them. To achieve this, define a user profile property with the single, restricted values of true and false. Then, in the Campaign Service configuration, use the Opt In
fields to enter the property set and name of the property containing that preference. E-mails will not be sent to users who have their property value set to false.
<PortalWebProject>/campaigns/emails
. If you want to use a different directory for storing e-mail files, follow the instructions in the next step.If you are using e-mails in your campaign, you can choose to send the e-mails in batch mode or real-time (batch mode is the default). In batch mode, when you run or test your campaign, e-mails are not sent. See Setting Up Bulk E-Mail Messages to learn how to change the mailing behavior to real-time
When a campaign sends an automatic e-mail, it uses a predefined e-mail message stored on the file system within your portal Web project. By default, WebLogic Portal prevents unauthorized access to those e-mail files when the files are stored in <PortalWebProject>/campaigns/emails
. Use the following information if you need to change the default e-mail security configuration.
Email files are secured by the following deployment descriptors:
<PortalApplication>/wps.jar/META-INF/weblogic-ejb-jar.xml
- The following line in this file provides the name of a user who is in the global PortalSystemAdministrator role:<run-as-principal-name> portaladmin </run-as-principal-name>
Membership in the global PortalSystemAdministrator security role is defined in the WebLogic Server Administration Console at the server level. In a portal domain created with the Configuration Wizard, the groups "Administrators" and "PortalSystemAdministrators" that are provided by default are configured to be members of the global PortalSystemAdministrator role. Because the user "portaladmin" (also provided by default in a portal domain) is a member of the portal "Administrators" and "PortalSystemAdministrators" groups, "portaladmin" is a member of the global PortalSystemAdministrator role.
If you need to use a different user for e-mail security: 1) Back up wps.jar; 2) Un-jar wps.jar and change the name of the user in weblogic-ejb-jar.xml; 3) Make sure the user exists; 4) Make sure the user is a member of the global PortalSystemAdministrator security role; and 5) Re-jar and replace the old wps.jar and redeploy the application. If you enter the name of a user in <run-as-principal-name> that does not exist, or if you delete the "portaladmin" user without changing the <run-as-principal-name> entry, you will receive deployment errors on wps.jar.
<PortalWebProject>/WEB-INF/web.xml
- The following line in this file secures the e-mail files in <PortalWebProject>/campaigns/emails
, allowing only the campaign service (through the PortalSystemAdministrator user defined in the previous section) to access and send the e-mails:<url-pattern>/campaigns/emails/*</url-pattern>
If you need to use a different directory for storing e-mail files:
1) Change the <url-pattern> path in web.xml to ensure the files in the new directory are secured.
2) In the WebLogic Administration Portal, choose Service Administration > Campaign Service, and change the directory in the Base Directory for Email Browsing field.
3) Redeploy the application.
Note: Using a wildcard character (*) in the URL pattern does not provide recursive directory protection. The wildcard protects only the files in the last directory listed. For example, if you want to store e-mail files in /campaigns/emails/q1
, the url-pattern /campaigns/emails/*
does not protect the e-mail files in the /q1
directory. To protect those e-mail files, the url-pattern must be /campaigns/emails/q1/*
.
You must use a command to periodically send the batch e-mails 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.
For Windows, the send-mail
command is located in a .bat
file wrapper script. For UNIX, the send-mail
command is located in a .sh
file. The following sections refer to the .bat
file. UNIX users should substitute .sh
for .bat
.
Note: When you send campaign e-mails, the default is set to true
to use a batch mode operation. Batch mode requires you to run the mailmanager.bat
file from the <root>/weblogic81/portal/bin
directory to send the e-mails through the SMTP server. For WebLogic Workshop 8.1.x, you can request a patch to modify the batch flag
to change it to false
to send the campaign e-mails in real-time.
This section contains the following topics:
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). If you use the send-mail
script from any other configuration, you must modify the script.
Perform the following steps to run the send-mail
script from a remote host (a computer that is not a WebLogic Portal host):
SET HOST=
line. Replace localhost with the name of a WebLogic Portal host.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.
Note: The following steps must be performed on each host that will run the script.
Perform the following steps on each host to use the send-mail
script in a clustered environment:
mailmanager
script, replace localhost
in the SET HOST=
line 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.The mailmanager
command is a wrapper script that uses the jav.com.bea.p13n.mail. MailManager
class.
Use the following command syntax:
mailmanager.bat [ appName ] [ list | send | send-delete | delete ]
(
batch-name ]mailmanager.sh
on UNIX)
If you specify only the appName
arguments, the mailmanager
command prints to standard output the names all e-mail batches in the application and the number of e-mails in each batch.
Table 5-1 contains a list of the command arguments.
Table 5-2 contains examples of mailmanager
commands.
Perform the following steps to send bulk e-mail from a shell that is logged into a WebLogic Portal host:
mailmanager.bat appName list
(Windows)
The appName
is the name of the enterprise application that generated the e-mail batch. The command prints to standard output. You can use shell commands to direct the output to files.
mailmanager.bat appName send-delete batch-name
Note: If you are using e-mails in your campaign, you can choose to send the e-mails in batch mode or real-time (batch mode is the default). In batch mode, when you run or test your campaign, no e-mails will be sent. See Setting Up Bulk E-Mail Messages to learn how to send batch mode emails and how to change the mailing behavior to real-time.
You can use a scheduling utility to send the e-mail batches in the data repository. You must specify the name of a batch when you use the mailmanager
command to send mail, so you must schedule sending mail for each campaign scenario separately. The name of a batch corresponds to the scenario's containerId
. The containerId
specifies the ID of the campaign to which the scenario belongs.
For information in using a scheduling utility, refer to your operating system's documentation.
You can delete e-mail batches after you send them (see Sending Bulk E-Mail).
You can also perform the following steps to delete e-mail batches:
mailmanager.bat appName list
The appName
is the name of the enterprise application that generated the e-mail batch. The command prints to standard output. You can use shell commands to direct the output to files.
mailmanager.bat appName delete batch-name
If you are going to create discount campaign actions, perform the following steps. For details on these steps, see "Building a Commerce Application" in the WebLogic Workshop help system at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/buildportals/navCommerce.html.
You must use a Regular or Behavior Tracking event to begin your campaign or trigger a campaign action based on events and their values. A commonly used event is SessionLoginEvent
.
See Using Events in Campaigns and Registering Events for Campaigns for instructions. See also How Campaigns are Triggered.
For instructions on using all the previously mentioned pieces to create a campaign in WebLogic Workshop, see "Creating Campaigns" in the WebLogic Workshop help system at http://download.oracle.com/docs/cd/E13226_01/workshop/docs81/doc/en/portal/buildportals/createCampaigns.html.
Use the following guidelines for creating campaigns:
To use session or request properties to trigger campaign actions, make sure you do the following:
Note: When you send Campaign emails, the default is set to true
to use a batch mode operation. Batch mode requires you to run the mailmanager.bat
file from the <root>/weblogic81/portal/bin
directory to send the e-mails through the SMTP server. For WebLogic Workshop 8.1.x, you can request a patch to modify the batch flag
to change it to false
to send the Campaign e-mails in real-time.
You can reset different aspects of your campaigns. For example, you may want to do one or all of the following:
You can reset campaigns either in the development environment (for testing) or in the production environment.
With a campaign file open, choose Portal --> Reset Campaign. The Reset Campaign dialog box appears, as shown in Figure 5-1.
For details on using this feature for testing, see Testing Campaigns in this chapter.
Figure 5-1 Resetting a campaign in the development environment
To reset a campaign in the production environment, select the campaign in the WebLogic Administration Portal and click the Reset Campaign button. The Reset dialog box appears, as shown in Figure 5-2.
Figure 5-2 Resetting a campaign in a production environment
Use the following guidelines for testing campaigns in your development environment on your development server:
See Tuning for Campaigns in the Performance Tuning Guide.