Using Extensions

This chapter provides an overview of the process of creating Extensions. It contains the following sections:

• Understanding Extensions

• Overview of Benefits and Usage

• Common Usage Scenarios

• Creating and Using Extensions

• Extension Programming Reference

• Sample Servlets

Understanding Extensions

This chapter assumes that you are familiar with the software development process and the creation of Java servlets and PeopleCode functions. It further assumes familiarity with the Online Marketing system and its architecture and database structure.

PeopleSoft recommends that you use the expertise of PeopleSoft’s technical consultants for the development of any Extensions you need, as they have expertise in writing Java servlets and PeopleCode functions along with a thorough knowledge of PeopleSoft Online Marketing and its database structure. If you are a licensed customer you can also use this documentation to develop extensions using your own software developers.

Note. Support of any custom-written Extension (defined as any extension that does not ship with the Online Marketing product) is not offered through PeopleSoft’s Customer Connection organization. Therefore, if you choose to develop Extensions in-house and need assistance (such as troubleshooting or testing assistance) beyond what this documentation provides, contact your PeopleSoft account manager who can help you decide which consulting services are appropriate.

There are two kinds of Extensions:

• Custom Content: Extensions included in Online Marketing documents.

• Custom Actions: Extensions included in the Online Marketing Dialog process

Overview of Benefits and Usage

Online Marketing provides the ability to merge data dynamically into documents using the Merge capability. The custom content extension extends this capability by allowing you to merge in external, customized content dynamically based on the profile interests of each recipient and your marketing strategy.

The custom action extension enables you to extend actions in the dialog process. Custom actions are custom Java Servlets or People Code Application classes that can execute business logic, update or retrieve profile information, and even retrieve or post information to external systems. You can insert custom actions as subtasks in both the Reach and Response actions of the Online Marketing dialog process.

Common Usage Scenarios

The following scenarios show examples of how Extensions can be used.

Custom Content Scenarios

The following scenarios illustrate some uses for custom content.

• A music e-retailer sends out a weekly email newsletter to its 10,000 registered subscribers. A Custom Content servlet enables the content in the newsletter to be customized, inserting that week’s top 10 country albums in one subscriber’s email with a web link in the content going to the Country section of the e-retailer’s website, while another subscriber receives the list of the top 10 R&B albums with a link to the R&B section of their website.

• A networking company sends out a weekly customer newsletter. When the customers sign up to receive it, they can specify which of the 6 categories of the newsletter are of interest to them. Each week, they get new content delivered for their categories. At any time, they can modify their profiles to change which categories they wish to receive, and that change will be reflected in their next newsletter.

• An online mortgage broker gathers preferences from customers on the specific types of loans they are interested in (home, car, etc.), the terms of the loan (fixed, variable, balloon payments), the overall amount of the loan, and so on. Customers opt in to receive email each time a new loan is available that meets their criteria. Each day, the new loan data is loaded in the broker’s database. Online Marketing is used to send out a daily email that pulls the latest loan information from the broker’s database.

• A financial institution sends out a monthly financial update to their subscribers and tailors the information to the individual customer. If the customer is over 60 years old and has a 401K, the customer sees a section of their email which has information on low-risk mutual fund choices for 401Ks. If the customer is in the 20-30-year age bracket and does not have a 401K, that customer sees a section in their email encouraging them to set up a 401K, showing the benefits of starting to save when they are young.

Custom Action Scenarios

The following scenarios illustrate some uses for custom actions.

• A company would like to send leads that are generated using Online Marketing to their Sales Force Automation system. They would like to make sure the leads are well qualified before sending them, so they continuously update a prospects lead profile with the strength of a lead and the lead’s timeframe to buy. A custom action can take this profile information and export it into an SFA system on a scheduled basis or when triggered by an event such as a contact filling out a registration page.

• A company would like to distribute their leads using a “round-robin” system. For each sales rep in a region, the company wants to send one lead to each person in that region, then start again at the first person. Custom actions can be used to first determine the region where a lead should go (based on demographic or other information) and then to track where the next lead should be sent, ensuring that the correct rep receives the information.

• A company would like to update their Online Marketing profiles with information from their customer support database. They would like to know the last time that a customer opened a trouble-ticket so they can periodically follow up with a custom support survey. A custom action can be used to update the profiles in real time.

• A company wants to have multiple lead profiles for each contact, as one person can be interested in multiple products at different times. A custom action can update their lead profile, a “many rows per contact” profile. As a prospect fills out a registration form, they answer questions that help the company determine how strong a lead that prospect is. Using a custom action, they can populate the lead profile with the quality of the lead (Hot, Warm, or Cold), where the lead was generated, and other information from the qualification questions (such as their timeframe to buy and whether they have an approved budget).

Creating and Using Extensions

Creating and using an Extension consists of the following steps. Each step will be described in greater detail in this section.

1. Define your extension requirements

2. Write the extension (a Java servlet compiled into class files or a PeopleCode Application class). If your extension is developed in People Code, you can skip step 3.

3. Package your extension java class file in a jar file and supply the name of the jar file directory in the extensionsDir parameter (set on the Online Marketing Settings page).

4. Register the extension using Online Marketing.

5. For custom content extensions, insert the Online Marketing formatted syntax using the Merge Content page to choose an extension, then specifying any needed parameters and their values in the desired email or web document. For custom action extensions, insert the custom action in the dialog process, specifying any needed parameters and their values.

6. Test the extension in a development environment.

7. Test the extension on your Online Marketing production system, testing the dialog that uses the extension.

8. After the dialog is successfully tested, go live with the test dialog to a test audience.

9. Go live with the extension in a production dialog to the desired audience.

See Also

Designing the Flow for an Online Dialog

Designing Web Documents

Designing Email Documents

Defining Extension Requirements

Every Extension is different, determined by the business needs of the person who will be using it. Before you begin work on an extension, ascertain your business needs. Determine what you want the extension to do, any particular needs or wishes you have, and what your expectations are (including expectations for error handling). Try to get as much specific detail as you can—the more you understand your needs, the more effectively you can meet them.

After you have determined your needs, create a detailed statement of work describing the extension, what it will do, the parameters it needs, and how you will implement it. Create a design for the extension before you begin writing it.

Write the Java Servlet

It is beyond the scope of this chapter to describe the general process for creating a Java servlet. However, there are some aspects of servlet creation specific to an Online Marketing Extension servlet. These are discussed in this section. Also, Online Marketing ships with three sample servlets named HelloWorld, SampleLiveExtension, and EXStockQuotes, which you can find in com.peoplesoft.crm.omk.examples.jar. You can use these servlets for custom content extension testing purposes and as a guide for creating your own servlets.

Servlet Imports

The servlet should include the following import statement to access the Extension framework:

import com.peoplesoft.crm.omk.external.GenericAnnuncioServlet

Note. The class of com.peoplesoft.crm.omk.external.GenericAnnuncioServlet is included in the jar file com.peoplesoft.crm.omk.jar, so you can use it to compile your extensions. This jar file can be found in the PeopleSoft Application Server install root/class directory.

Servlet Class Inheritance

The servlet class should be declared to extend the GenericAnnuncioServlet class. For example:

Public class myDemoServlet extends GenericAnnuncioServlet

This extension provides access to logging and tracing.

Note. Because the GenericAnnuncioServlet class is extended from Java servlets (not from HTTP servlets), the Extensions framework does not fully support HTTP protocol (such as HTTP sessions).

Output

Extension output for merge purposes can use the standard servlet ServletOutputStream provided with the servlet class via its response mechanism.

Note. Output is applicable only to custom content extensions; it will be ignored by custom action extensions.

Extension Framework Error Handling

The Extension framework handles errors for custom content extensions in the following ways, depending on the type of document:

Extensions That Call Classes in External jar Files

If the custom extension needs to call classes in external jar files (such as CI methods or third-party methods), then these jar files must be added to the webserver's system classpath to be available to the extensions. The procedures for doing so are as follows:

WebLogic:

1. Put the jar files in a known location (for example, C:\Jars\myci.jar).

2. Go to <PS_HOME>/webserv/omk.

3. Open the setenv.cmd file.

4. Scroll to near the end, where you will see a line setting the CLASSPATH variable. For example:

   SET CLASSPATH=%PSCLASSPATH%;%PLATFORM_PATCH%;%JAVA_HOME%\lib\tools.jar;%WL_HOME%\
   server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\weblogic.jar
   

5. Add your jar file location to the end of the CLASSPATH setting. For example:

   SET CLASSPATH=%PSCLASSPATH%;%PLATFORM_PATCH%;%JAVA_HOME%\lib\tools.jar;%WL_HOME%\
   server\lib\weblogic_sp.jar;%WL_HOME%\server\lib\weblogic.jar;c:\Jars\myci.jar
   

6. Restart the DES server.

WebSphere:

1. Go to the lib directory of the WebSphere installation.

2. Put the external jar file in this directory.

3. Restart the DES server.

Write the PeopleCode Function

It is beyond the scope of this chapter to describe the general process for creating a PeopleCode function. Refer to your PeopleCode documentation for more information.

Note. PeopleCode extensions can only be used as Custom Actions in the Online Marketing dialog flow.

Example PeopleCode Function

The following is an example extension, written in a PeopleCode extension class, that uses MessageBox to write its parameter names and values to the Application Server log:

import RY_DATAOBJS:*;

class CustomAction;
   method CustomAction();
   method actionMethod(&params As MapObj);
end-class;

method CustomAction
end-method;

method actionMethod
   /+ &params as RY_DATAOBJS:MapObj +/
   Local string &msg;
   Local array of string &keys;
   Local integer &i;
   &msg = "actionMethod(";
   &keys = &params.keys();
   For &i = 1 To &keys.Len
      If &i > 1 Then
         &msg = &msg | ",";
      End-If;
      &msg = &msg | &keys [&i] | "=" | &params.get(&keys [&i]).value;
   End-For;
   &msg = &msg | ");";
   
   MessageBox(0, "", 0, 0, &msg);
end-method;

The custom action receives a single parameter of type RY_DATAOBJS:MapObj. This is a name/value map which maps parameter names to parameter values. All names are strings; all values are of type RY_DATAOBJS.StringObj.

To get a PeopleCode string from StringObj, use its value property. The contents of the map will consist of all parameters defined when the action was registered, any additional parameters added when the action was included in a dialog, plus any document/profile fields on the page that was submitted to cause the action to be invoked.

PeopleCode actions are invoked asynchronously, and need not return a value.

See Also

Enterprise PeopleTools 8.48 PeopleBook: PeopleCode Language Reference

Enterprise PeopleTools 8.48 PeopleBook: PeopleCode Developer's Guide

Install the Extension Class Files on DES and Mailcaster Machines

If you have written a Java servlet for your Extension and compiled it as class files, perform the following installation steps:

1. Add the class file in a jar file with the full package path.

2. Set the jar file name on the Extension Registration page.

3. Put the jar file in a directory that includes other Extension jar files for Online Marketing. The directory name must be set to the value of the parameter extensionsDir on the Setting page.

If the DES and Mailcaster are installed on different machines, and the location of the extension jar file is not accessible from one of the machines, the extensionsDir value for individual service can be overwritten in the service's configuration file. For example, if the Extension jar can be accessed from DES, but not from all the Online Marketing other services (Mail service, WatchDog, and Email Response Processor), you should do the following:

1. Install the Extension jar file in a location accessible to DES. Set the jar location to extensionsDir in the DES Settings page.

2. Install the Extension jar file in a location where it is accessible to other Online Marketing services (such as Mailcaster).

3. For each services instance, add extensionsDir="extension jar dir" (see step 2 above) in the relevant configuration file (for example, MCR.config for Mailcaster).

In this case, DES will load the Extension jar file by using the value of extensionsDir from settings, and the Mailcaster will load the Extension jar by using the value of extensionsDir from the MCR.config file.

Create the Online Marketing Formatted Syntax

For custom content extensions (used in web and email documents), merge content is used to specify an extension to be executed. The merge content format is similar to the Online Marketing merge content format. It is not necessary to create this Online Marketing formatted syntax for custom action extensions.

The basic format for custom content extensions is:

<pstag:extension name="<name>" default="<details of function>" id="<VC Reference ID>"/>

The merge content identifier that identifies the extension to execute is pstag: extension name=”<name>”, where

This tag must appear first in the merge content syntax. For example:

<pstag:extension name="Hello" default="<details of function>" id="1234" />

Global Extension Parameters

The following parameters can also be used in Extensions, and can appear in any order. These parameters apply to both custom content and custom action extensions. They are set in the Settings feature.

Notes on Designing Extensions

The following usage notes describe things you should be aware of when creating and using Extensions.

• Caching Extensions

  Because caching custom content extensions has a direct impact on the WebLogic or WebSphere Application Server memory usage, you may need to modify the memory settings of the webservers to support cache content. You should tune elements of the system based on usage; caching all extensions is not necessarily a good idea. Exceeding the memory size value can result in unpredictable DES behavior.

• Checking for Timeout

  The Extension framework cannot force a running servlet to stop when it is timed out—it can only request that the servlet stop processing and clean up after itself. Therefore, a well-behaved servlet should periodically check to see if it has been timed out, and stop processing if it has been.

  The recommended way to do this is to check to see if the servlet's thread has been interrupted. This can be accomplished using the following call sequence:

  import java.lang.Thread
  ...
  boolean keepRunning = Thread.currentThread().isInterrupted();
  if (!keepRunning)
  {
  	//... cleanup and exit code goes here
  }

  Note that default timeouts have an order of precedence depending on where they occur. The order in which they are used, from first to last, is:

  1. The value specified in the merge content.

  2. The value specified where the extension is registered

  3. The global default value registered for the Extension framework

  4. The internal, hard-coded default

  A good rule to follow is that you should not specify a timeout in merge content unless it is very important to override the more general defaults.

• Throwing Exceptions

  If the extension is to be used by the Mailcaster, you have control as to whether the entire job or only a single email is aborted.

  If you want to abort the entire job, the servlet should throw a ServletException. You should do this, for example, if there is some resource needed for all contacts that is unavailable. The user can then reschedule the mail job after the problem is corrected.

  If you want to suppress the sending of mail to the single contact then a VCSingleContactException should be thrown. This would be useful in the case where a resource for a single end user was not available.

Register the Extension in Online Marketing

To register and configure the Extension, you must have Dialog Administrator permission or permission to change settings.

Follow these steps to register and configure extensions:

1. Navigate to Set Up CRM, Product Related, Online Marketing, Extension Summary.

   The Extension page displays a list of current extensions.

2. In the Implement Type list, specify if the extension you want to register is a Java servlet or a PeopleCode application class.

3. Click the Add Extension button.

Registering a Java Extension

Access the Extension Registration page.

Name	Specify a name for the extension. Spaces are allowed.
Description	Enter a brief description of the extension's function.
Status	Indicates whether the extension is ready for use by the system. An extension starts in the In Design status. You can change it to Active when it is ready to be used. Once an extension is Active, you can change it to Archived to prevent new references or usage in a document or flow. (Existing references will still continue to work.)
Type	Indicates whether the extension is written in Java or PeopleCode.
Usage	Select In Document if the extension is to be used to retrieve content for display in a document, or Process if the extension will perform a function as part of the dialog process.
Servlet Class Name	Specify a class name for the Java servlet, using the fully qualified name of the servlet (for example, com.peoplesoft.crm.omk.external.HelloWorld).
Servlet Jar File Name	Specify the name of the servlet's jar file.
Wait Return Before Process	Select this check box if the extension is to be processed synchronously, or leave it cleared if the extension is to be processed asynchronously.
Timeout	If specified, this value will override the global default specified in the extensionTimeout parameter set in the Settings component.
Custom Action Icon	When you select In Process as the Usage, you can upload a custom icon that will appear in the dialog flow when the custom action is selected. Click Upload Image to specify an image, or Delete Image to remove a previously specified image. If you do not supply a custom icon, the default custom action icon is used.
Parameters	You can define a default list of parameters for the extension during registration. These values can be overwritten by individual references to the extension in the Custom Action or Custom Content objects. All the parameters and values from the registration page, along with the overwritten or additional parameters from the specific references are passed to the system for processing. You cannot use merge content syntax in the parameter or value fields on the registration page.
Add Parameter	Click this button to add a new parameter to the list.

Note. If your extension requires third-party classes that came in a separate jar file from the extension jar file, you must package the third-party classes in the extension jar or else ensure that the third-party jar is available in the web container's class path.

Registering a PeopleCode Extension

Registering a PeopleCode extension is similar to registering a Java extension, except that a PeopleCode extension cannot be used in the Dialog Process tree. Because of this, the Usage check box is selected and disabled.

Application Class Path	Enter the application package and class name for the PeopleCode function.
Class Method	Enter the method of the application class.

See Register the Extension in Online Marketing.

Managing Extensions

Only users with the role of Dialog Administrator can register extensions or change global settings. Once an extension is registered and its status set to Active, it cannot be deleted from system. However, the following modifications can be made, depending on the extension's status:

System Delivered Extension

One system extension, Update Case Score, is delivered in this release. It is used by Case Integration to update survey scores to Support and HelpDesk. You cannot modify the Update Case Score extension using the Extension Registration page, which is disabled for this extension.

See Understanding Surveys.

See Sending Case Surveys.

Custom Action Runtime Behavior

If you will be using custom actions to update profiles (for example, updating a profile value to a document field value or a fixed value), it is important to understand custom action runtime behavior.

The Update Profile custom action updates the profile data to the cache first. It saves the information to the database with other profile updates after all the actions are completed and before it displays the next page to the user.

Custom Action Runtime Behavior: Extension Management

If Custom Actions are used in updating user profiles (such as updating a user profile using values from document fields or fixed values), the Update Profile Custom Action updates the profile data in the cache first. The Custom Action saves to the database with all other profile updates after all of the actions are completed, and before returning the next page in the dialog flow.

Note that in the case where a Custom Action must read data from Custom Profiles (User Defined Profiles), or other Customer Data Model (CDM) profile data from database, a Page Submit action is required in order for the data to be saved to the database so that a Custom Action can read that data. To accomplish this, use an Intermediate Page Action to ensure that data is submitted to the database before the Custom Action occurs in your Dialog Flow. Custom Actions that occur before a Final Page action do not meet this requirement as the Final Page action has no Submit action.

Since profile data from Online Marketing web pages and Update Profile actions are saved to the database at the end of action execution, data from a Custom Action is saved only after it is executed. Therefore, it is recommended that in order for a Custom Action to access current profile data, it should make use of the Profile based Variable Contents in the Custom Action parameter.

Test in a Development Environment

Before attempting to deploy the Extension in a production environment, test it thoroughly in a development environment.

Test in a Staging Environment

After you have configured the Extension, test it in a staging environment, within a test dialog, to a test audience. If possible, test in an independent development system that “mirrors” the production system because the impact to the system and the DES is unknown until the Extension has been tested.

Go Live!

First, you should go live with the Extension on your production system, using a test dialog and a test audience.

After completing testing of the extension, you are now ready to deploy it in a production dialog to your desired audience.

Extension Programming References

This section provides reference information useful when writing your own Extensions. The following topics are covered:

• Reserved Words

• Merge Content Syntax

• Available CGI Environment Values

• RFC 2616 Request Headers

• Netscape Enterprise Server-Specific Request Headers

Reserved Words

The following reserved words should not be used in your extensions except when using them in their explicit Online Marketing-specific sense.

• name

• timeout

• async

• default

See Create the Online Marketing Formatted Syntax.

Merge Content Syntax

Merge content can be used when calling the extension in parameters or within the actual servlet code.

The following is the basic syntax for merge content:

{pstag:vctype [value="value"]
		[ default="defaultValue"]}

where

See Merge Content Specification.

Extension Merge Content—Company

The merge content syntax for companies in the profile database is:

	<pstag:profile value="Organizations.profileName.fieldName" />

where

The following examples show Extension parameter merge content where a parameter value is set to be the value of Company merge content:

<pstag:profile value="Organizations.Companies.Organization Name" />

<pstag:profile value="Organizations.Companies.ZIP Code" />

<pstag:profile value="Organizations.Companies.Web Site Address" />

<pstag:profile value="Organizations.Companies.Organization Phone" />

Extension Merge Content—contact

The merge content syntax for people in your profile database is:

	<pstag:profile value="Individuals.profileName.fieldName" />

where

The following examples show Extension merge content where a parameter value is set to be the value of Individuals merge content:

<pstag:profile value="Individuals.People.Source ID" />
<pstag:profile value="Individuals.People.Email" />
<pstag:profile value="Individuals.People.ZIP Code" />
<pstag:profile value="Individuals.People.Last Name" />

Extension Merge Content—document

The merge content syntax for documents is:

	<pstag:document value="documentName.fieldName" id="VC Reference ID"/>

where

The following example shows an Extension merge content where a document is used in merge content:

<pstag:document value="doc_enter.ticker: id="123" />

Extension Merge Content—Constants

Constants can be passed as parameters to extensions or called from within the extension. The merge content syntax for constants is:

	<pstag:constantName/>

where

The following examples show Extension merge content where a constant is used in merge content:

<pstag:currentTime format="HH:MM" />
<pstag:recipientID/>
<pstag:dialogID/>

The following constants can be called in Extension constant merge content.

• emailTrackingBlock

• trackingNumber

• url

• currentDate

• currentTime

• recipientID

• baseURL

• activate_page_action_name

• dialogID

• actionID

• response_handler_id

• sourceActionID

• individualID

• organizationID

• individualBOID

• organizationBOID

• individualRoleTypeID

• organizationRoleTypeID

• documentLanguageCode

• dialogBusinessUnit

• documentSetID

Available CGI Environment Values

The following CGI environment values are available for inclusion in Extensions. These values are typically passed from the web server.

• SERVER_NAME

• SERVER_PROTOCOL

• SERVER_PORT

• REQUEST_METHOD

• PATH_INFO

• PATH_TRANSLATED

• PATH_TRANSLATED

• SCRIPT_NAME

• DOCUMENT_ROOT

• QUERY_STRING

• REMOTE_HOST

• REMOTE_ADDR

• AUTH_TYPE

• REMOTE_USER

• CONTENT_TYPE

• CONTENT_LENGTH

• HTTP_ACCEPT

• HTTP_USER_AGENT

• HTTP_REFERER

RFC 2616 Request Headers

The following RFC 2616 request headers are available for inclusion in Extensions.

• Accept

• Accept-Charset

• Accept-Encoding

• Accept-Language

• Accept-Ranges

• Age

• Allow

• Authorization

• Cache-Control

• Connection

• Content-Encoding

• Content-Language

• Content-Length

• Content-Location

• Content-MD5

• Content-Range

• Content-Type

• Date

• ETag

• Expert

• Expires

• From

• Host

• If-Match

• If-Modified-Since

• If-None-Match

• If-Range

• If-Unmodified-Since

• Last-Modified

• Location

• Max-Forwards

• Pragma

• Proxy-Authenticate

• Proxy-Authorization

• Range

• Referrer

• Retry-After

• Server

• TE

• Trailer

• Transfer-Encoding

• Upgrade

• User-Agent

• Vary

• Via

• Warning

• WWW-Authenticate

Netscape Enterprise Server-Specific Request Headers

The following Netscape Enterprise Server-Specific request headers are available for inclusion in Extensions.

• auth-user

• REMOTE_USER

• ip

Sample Servlets

This section provides information about the sample servlets shipped with Online Marketing Extensions:

• HelloWorld

• SampleLiveExtension

• EXStockQuotes

The HelloWorld servlet is a small extension you can use to test custom content extensions. The SampleLiveExtension servlet is designed to show some possibilities of the Online Marketing Extension architecture. Both are described in detail in this section.

The EXStockQuotes servlet, also included, is described briefly on page 94.

Location of Sample Servlets

For all of the sample servlets, the class files are provided and are packaged in the jar file com.peoplesoft.crm.omk.examples.jar.

where selected_path is the pathname where you chose to install the files.

Note. The files exist on machines where Online Marketing Dialog Server or Mailcaster is installed.

The “HelloWorld” Servlet

The test Java servlet named HelloWorld can be used to test custom content extensions. The following shows the source for this servlet.

//******************************************************************/
//        Confidentiality Information:                              /
//                                                                  /
// This module contains confidential and proprietary information    /
// of PeopleSoft, Inc.; it is not to be copied, reproduced, or      /
// transmitted in any form, by any means, in whole or in part,      /
// nor is it to be used for any purpose other than that for         /
// which it is expressly provided under the applicable license      /
// agreement.                                                       /
//                                                                  /
// Copyright (c) 2000-2002 PeopleSoft, Inc. All Rights Reserved.    /
//******************************************************************/
/*--- formatted by Jindent 2.1, (www.c-lab.de/~jindent) ---*/

package com.peoplesoft.crm.omk.external;
import java.io.PrintWriter;

/**
* HelloWorld servlet simply outputs the string "Hello World!"
*/
public class HelloWorld extends GenericAnnuncioServlet
{
		/**
		* HelloWorld constructor.
		*/
		public HelloWorld()
		{
			super();
		}
		/**
		* Retrieves the servlet info string
		* @return String the servlet info string
		*/
			public String getServletInfo()
		{
			return ("HelloWorld, Annuncio Software, 4/2000");
		}
		/**
		* service method.
		*/
		public void service(javax.servlet.ServletRequest req, 	
		javax.servlet.ServletResponse res) 
				throws javax.servlet.ServletException, java.io.IOException
{
		PrintWriter out = res.getWriter();
		if (out != null)
	{
			out.print("Hello World!");
		}
		else
		{
			System.err.println("Can't get a PrintWriter.");
		}
	}
}
/*--- formatting done in "Annuncio Convention" style on 06-20-2000 ---*/

The “SampleLiveExtension” Servlet

The SampleLiveExtension servlet is a custom content extension that builds HTML on a web page based on a content’s profile information. It shows how to achieve the following operations:

• Pass parameters, including profile information, to a Online Marketing Extension

• Retrieve external data to be merged into a document

• Manage a cache to improve performance while ensuring thread safety:

  • Refresh mechanism

  • Access synchronization

• Log error messages to the Online Marketing log files

This section is divided into the following subsections:

• Audience: who should use this Online Marketing Extension?

• Functionality: What the Online Marketing Extension does

• Content storage: How the extension stores the content in files

• Cache mechanism: Which rules determine the reloading of the content

• Registering the extension: How to register the extension with the Online Marketing Dialog Server

• Using the extension: How to build a simple dialog using this extension

Audience

The audience for this extension consists of users who want to understand Online Marketing Extensions and those who want to write them.

Warning! This extension is provided as an example only; it should never be used in a production dialog.

Functionality

The SampleLiveExtension servlet expects the following parameters:

The servlet displays the following message:

• A welcome message:

  • “Welcome!” if the first name of the contact is unspecified

  • “Welcome, <First Name>!” if the first name of the contact is known.

• Data about the state given as a parameter:

  • If no state is specified, a detailed error message is displayed

  • If no data is available for that state, a detailed error message is displayed

  • If some data is available for that state, it is retrieved and displayed.

Content Storage

The servlet expects that the content is stored in files. The path of the files must be specified in the path parameter. File names should be in the following format:

<path_value>\<state_abbreviation>.txt

For example, if the path is equal to C:\states\ and the state is California, the data would be searched in the following file:

C:\states\CA.txt

The content of each state data file is expected to be a list of key/value pairs. The following keys are searched and merged into the document:

• Population

• Area

• Senators

A valid file would look similar to this:

Population=33,145,121 inhabitants
Area=158,869 square miles
Senators=Barbara Boxer, Dianne Feinstein

All information available in the file will be displayed on the web page.

Cache Mechanism

To limit the number of disk accesses, the content of each file is kept in memory after being read. However, two mechanisms are implemented to allow the update of the data:

• If the refresh parameter is set to true, any data in the cache is removed. The data to display will be automatically reloaded from the file and not pulled from the cache.

• If the refreshTime has been crossed since the last loading of the data, the content is automatically refreshed from the file.

Note. The use of the refresh parameter only refreshes the cache on the Online Marketing component where the servlet is executed—this can be the Online Marketing Dialog Server (for web page content) or a Mailcaster (for email content).

Registering the Extension

Before you can use the SampleLiveExtension servlet, you must register it.

Note. The design of the SampleLiveExtension servlet is more appropriate for usage as a custom content extension within a web page. However, it can also be used as a custom content extension within an email. The following registration instructions allow the registration of the servlet on the Online Marketing Dialog Execution Server, which is used to display web page content. If you want to use the extension with email, you must register the function on all the Mailcasters. (In this case, step 1 in the following instructions must be done only once in Extension Registration, but steps 2 and 3 must be done for each component that will call the extension.)

Follow these instructions to register the servlet:

1. Navigate to the Extension Registration Page for Java servlets and add the servlet SampleLiveExtension. Set the following parameter values within it:

   Name	Value
   Servlet Class Name	com.peoplesoft.crm.omk.external.CFlibrary.SampleLiveExtension
   path	The path where you will store the files containing the content. You must include a final backslash (\) for Windows or slash (/) for Solaris, for example: C:\states\ or /usr/foo/states/
   refreshTime	The time when you want the content to be refreshed each day.

2. Change the status to Active and save the changes.

3. After you have finished, restart the Dialog Execution Server.

4. If you are calling the extension from an email, restart the Mailcasters that will call this extension.

See Register the Extension in Online Marketing.

See PeopleSoft Online Marketing User Guide.

Using the Extension

One of the simplest dialogs that allows you to use the SampleLiveExtension servlet is composed of the following:

• One landing page where the contact can submit personal information, including at least:

  • First name

  • Email address

  • State of residence

• A final page containing a call to the Online Marketing Extension that will generate the whole content.

• A web link to the landing page.

The call to the Online Marketing Extension would look like this:

<pstag:extension name="SampleLiveExtension"
 id="a number">

You can use the previous example as a model.

Hint: You can associate the refresh parameter with the value of a Yes/No document field on the landing field so you can easily see its effects.

After the files with the content have been created, you can set the dialog to Live (or In Test), generate a link report, and try out the functionality of the Online Marketing extension.

Additional Sample: EXStockQuotes

An additional sample servlet, EXStockQuotes, is also provided. It is similar to the SampleLiveExtension servlet.

You can use the EXStockQuotes servlet in three different ways within Online Marketing dialogs:

• Insert it directly into broadcast or follow-up emails

• Insert it directly into web documents

• Insert it into the Content section(s) of a Dynamic Content object in an email document

In the third scenario the extension is used to retrieve content posted at an external URL, while the conditions specifying which content is to be displayed to whom are set up within the Dynamic Content object (in Online Marketing). Typically in this case, as in this sample, one or two parameters would be passed to retrieve the appropriate content. Each Content Section of the Dynamic Content object could have an extension inserted to retrieve content, or the Dynamic Content object could have a mix where some Content Sections have internally-stored content (content that is inserted or copy/pasted into the Content tab) while other Content Sections have an extension designed to retrieve content.

See Also

The “SampleLiveExtension” Servlet