WebSphere Personalization for Multiplatforms Version 4.0 Installation Guide

 

Installing WebSphere Personalization for Multiplatforms V4.0

This document describes the prerequisites and steps necessary to install WebSphere Personalization for Multiplatforms V4.0.

WebSphere Personalization V4.0 uses a single suite installer for the four components: server, workspace, wizards for Studio, and the InfoCenter. The installation program will prompt you to select the components you want to install.

If you are unsure about which components to install, it is recommended that you refer to the InfoCenter. You can access it from the InfoCenter directory, or follow the instructions for installing it separately. The InfoCenter contains information about the development and runtime environments, and about how to plan a Personalization solution, that should be reviewed and understood before continuing with the installation of the other components.

For the latest information, download or view the English version of the README file, available on the IBM WebSphere Personalization library page:


http://www.ibm.com/software/webservers/personalization/library.html

 

Server

WebSphere Personalization V4.0 server, which includes the rules engine, resource engine and related APIs, and the WebSphere Personalization Resource Console, is installed as an add-on to WebSphere Application Server. Install the Personalization server on any server that processes and delivers JSPs with personalized content, such as test, preview or staging servers, or production servers.

 

Prerequisites

The prerequisites for WebSphere Personalization V4.0 server are:

 

Preparing for installation

This section provides instructions for preparing for the server installation.

  1. Verify that all of the prerequisites have been installed and verified.
  2. If a current or previous version of WebSphere Personalization exists, uninstall it before continuing.
  3. Consider the following points about installation options:

 

Installation steps

  1. Verify that the steps in preparing for installation have been completed.
  2. Verify that the WebSphere Administrative Server is running.
  3. Stop all nonessential applications that are running on the computer where you will install Personalization.
  4. For installations on Linux and Unix, ensure that the locale is set correctly.
  5. If you are running the install program on an AIX system, ensure that the display resolution is not higher than 1024x768.
  6. Insert the WebSphere Personalization for Multiplatforms V4.0 CD into the CD drive.
  7. Start the installation program:
    1. Change to the directory for your operating system on the Personalization CD.
    2. Issue the command to start the installation at the command prompt:
    3. Follow the dialog instructions to install the product.

      4. Note: If you are using a Sybase database, you must change the setting for "Allows nulls by default" from false to true. If you fail to make this change, the install will proceed normally, but the Personalization server will not function correctly.

    4. Exit the program when the installation has completed.
    5. If the installation program has not automatically restarted the application server, you can restart now.
  8. Continue to the section Verifying the installation.

Verifying the installation

After you install WebSphere Personalization, verify that the components listed in this table are installed.

Component Installation Target Comments
JAR files The following files are installed in the path <was_root>\lib, where <was_root> is the WebSphere Application Server root directory:
  • brbClient.jar
  • brbServer.jar
The following files are installed in the path <was_root>\personalization\lib.
  • personalization.jar
  • prCommon.jar
  • PznBeans.jar
  • BRBeans.jar
  • Note: PznBeans and BRBeans are also located under the Personalization EAR directory
 The installation program also adds the <was_root>\personalization\lib to the application server's JVM system property ws.ext.dirs . To verify the property update:
  1. Open the WebSphere Administrative Console, or refresh the view if the Administrative Console is already open.
  2. Click the application server in the topology tree.
  3. Verify that the System properties line arguments field contains the ws.ext.dirs and pzn.root.dir additions on the JVM Settings view.
Enterprise application An Enterprise Application named Personalization Runtime is installed to run within a user-specified application server / server group.

The following EJB modules are added to each server to which Personalization is installed under the name PznBeans:

  • RHierarchy
  • PersAuthTrans
  • PersAuthCollec
  • PersCollecTrans
  • SecEnabler
  • AContent
  • SessionInfo
  • MapEJB
  • CacheOP
  • EmailHistory
  • EmailPromoModel
  • SlotMappings
  • PznLogger

The following EJB modules are added under the name BRBeans:

  • Rule
  • RuleFolder
  • RuleHelper

 

  
Sub-directories for debugging, importing, exporting and uninstall The sub-directories are created under <was_root>\personalization:
  • audit (used for rules auditing output)
  • backup (used to backup projects, servers, and accesscontrol folders during uninstall of Personalization Workspace
  • ImportExport (contains a sample Personalization resources XML file)
  • lib (personalization jar location)
  • publishedCampaigns
  • publishedRules (used by Studio Advanced Edition)
  • publishedResources (used by Studio)
  • pznConfig (location of personalization configuration files)
  • userConfig (location of personalization user configuration files)
  • userServlets (location of personalization servlets)
  • utils (contains the uninstall program)
 The audit, publishedCampaigns, publishedRules, and publishedResources directories are initially empty.
Personalization database The following tables are created in the Personalization database under the schema PZNADMIN:
  • ACONTENT
  • CACHEOP
  • EMAILHISTORY
  • EMAILPROMOMODEL
  • LOGGING
  • MAPEJB
  • NODEATTRIBUTES
  • PERSAUTHCOLLEC
  • PERSAUTHTRANS
  • PERSCOLLECTRANS
  • RHIERARCHY
  • RHSTRUCTURE
  • SECENABLER
  • SESSIONINFO
  • SLOTMAPPINGS

The following tables are created in the Personalization database under the schema EJB:

  • BRBEANS_RULE
  • BRBEANS_RULEFOLDER

 

The tables are part of the Personalization database.
Personalization Datasource and JDBC Driver A datasource named Pers DataSource and a JDBC driver named Pers DB Driver are added to the WebSphere administrative domain.  

If the Personalization database tables were not created during installation, you will need to do it manually.

Personalization uses tables created under two schemas: PZNADMIN and EJB. If your database requires it, make sure you have database users by these names. You can find ddl files that contain the database commands needed to create these tables on the installation CD, in the utils folder. The files are named Tablexxxxx.ddl, where xxxx indicates the database.

 

To access the WebSphere Personalization Resource Console:

  1. The Resource Console generates a temporary cookie to synchronize data you enter on different pages. Check your Web browser settings to ensure that the browser is enabled to receive cookies or to prompt you when a cookie is awaiting receipt.
  2. Use your Web browser to open the following URL:
    3. http://<host_name>/PersAdmin/adminframe.jsp
  3. The Resource Console main page appears. If a cookie prompt appears, receive the cookie. The cookie will be removed from your system when you exit the Resource Console.
  4. To display help for a page, click the Help button.

 

Workspace

The Personalization workspace is the user interface for creating Personalization rules and campaigns and assigning them to content spots on the pages of the Web site. It is a Web application added to WebSphere Application Server. A server with the workspace is either referred to as an authoring server, since rules and campaigns are authored there, or as a workspace server. If you want to access the workspace from a remote system, you need a workstation that can establish a network connection to the authoring server.

Note: The InfoCenter is automatically installed with the workspace.

 

Prerequisites

The prerequisites for WebSphere Personalization V4.0 workspace are:

 

Preparing for installation

This section provides instructions for preparing for the installation.

  1. Verify that all of the prerequisites have been installed and verified.
  2. Consider the following points about installation options:

 

Installation steps

  1. Verify that the steps in preparing for installation have been completed.
  2. Stop all nonessential applications that are running on the computer where you will install Personalization.
  3. For installations on Linux and UNIX, ensure that the locale is set correctly.
  4. Insert the WebSphere Personalization for Multiplatforms V4.0 CD into the CD drive.
  5. Start the installation program:
    1. Change to the directory for your operating system on the Personalization CD.
    2. Issue the command to start the installation at the command prompt:
    3. Follow the dialog instructions to install the product.

      4. Note: When prompted, provide a userID to use when accessing the workspace for the first time. See Accessing the workspace for more information about the userID.

    4. Exit the program when the installation has completed.

 

Accessing the workspace

To access the workspace after installation, type the following URL into your browser:

http://<host_name>/PersWorkspace/index.jsp

where <host_name> is the server to which you installed the workspace. Use the userID supplied during installation to sign in. Note: this userID has Administrator authority, and is the only userID that can be used to sign in to the workspace until additional userIDs are created. A user with Administrator authority can create new userIDs for the workspace within the workspace's Global Settings.

 

Wizards for Studio

The Personalization wizards are added to WebSphere Studio. You can use these wizards within Studio to create classes for accessing your user and content resources in the customer data store, create content spots, and work with application objects and resource collections. Using Studio, you can add content spots to Web pages, and then publish the content spots and pages to the servers where the Personalization server or the Personalization workspace are installed.

Studio is the only tool that can be used to create and publish content spots. However, you can use a Java IDE to create user and content classes, use a JSP editor to create JSPs that make use of Personalization rules, and use a Web site deployment tool to publish the pages.

 

Prerequisites

The prerequisite for WebSphere Personalization V4.0 wizards for Studio is:

 

Installation steps

  1. Stop all nonessential applications that are running on the computer where you will install the wizards.
  2. Insert the WebSphere Personalization for Multiplatforms V4.0 CD into the CD drive.
  3. Start the installation program:
    1. Change to the directory for your operating system on the Personalization CD.
    2. Issue the command to start the installation at the command prompt:
    3. Follow the dialog instructions to install the product.
    4. Exit the program when the installation has completed.

 

Accessing the wizards

The new wizards will be available the next time you start Studio.

To access the wizards, go to Studio's Tools menu and select Wizards.

An HRF Editor is also added. To launch it, highlight an HRF file from within a project in Studio, select Tools, then Edit With, then HRF Editor.

To access the updates to the Studio Guide:

  1. Open WebSphere Studio V4.0 Advanced Edition
  2. Click Help from the menu, then click Studio Guide.
  3. Information about Personalization Version 4.0 has now been distinguished from Version 3.5. For example, refer to the section How to personalize your pages (for Personalization V4.0).

 

InfoCenter

The InfoCenter contains all of the supporting documentation for planning and implementing a personalization solution, in HTML format. It is installed automatically with, and is accessible from, the Workspace. The InfoCenter option during the suite install allows you to create a separate installation to a directory of your choice.

Note: The Personalization V4.0 InfoCenter is a complete and self-contained Web site. It does not (nor should you attempt to) install information into the WebSphere Application Server InfoCenter, as in previous releases.

 

Prerequisites

The prerequisite for WebSphere Personalization V4.0 InfoCenter is:

Note: The InfoCenter is accessible directly from the install image. If needed, it can be manually copied.

Installation steps

  1. Stop all nonessential applications that are running on the computer where you will install the InfoCenter.
  2. Insert the WebSphere Personalization for Multiplatforms V4.0 CD into the CD drive.
  3. Start the installation program:
    1. Change to the directory for your operating system on the Personalization CD.
    2. Issue the command to start the installation at the command prompt:
    3. Follow the dialog instructions to install the product.

      4. Note: When prompted, indicate an empty directory where the InfoCenter will be installed.

    4. Exit the program when the installation has completed.

 

Accessing the installation

You can access the InfoCenter using your browser:

<install_dir>/Pers4InfoCenter/cc/main/docFrameset.html

where <install_dir> is the directory you indicated during installation (or the root directory of the CD), and cc is the applicable country or region code:

cccode cccode
deGerman jaJapanese
enEnglish (U.S.) koKorean
esSpanish ptBrazilian Portuguese
frFrench zhChinese (simplified)
itItalian zh_TWChinese (traditional)

 

Personalization Sample

WebSphere Personalization V4.0 includes a sample project (PersSample.ear) that demonstrates how to use Personalization to customize a Web site. The sample scenario involves the Web site for a fictitious toy manufacturer, YourCo Toys. The YourCo Toys site supports company personnel (employees and managers at factory and lab locations) and headquarters personnel who support the R&D, manufacturing and sales forces. The sample demonstrates how to tailor Web pages to provide content based on the user's role and personal preferences. The Web content includes company news, articles about the industry, and detailed information about the company products.

The sample project also includes a WebSphere Studio V4.0 wsr file that you can use to see how the sample's content spots and JSPs were created. You do not need to publish the Studio .wsr files in order to run the sample.

Please note that the YourCo Toys sample is in English only.

Preparing for installation

You can install the sample to be used with Personalization server, to be used with Personalization workspace, or to be used with both the Personalization server and workspace. To use the Preview function in Personalization workspace you must install the sample to be used with both the Personalization server and workspace.

 

Installation steps

To install the sample to be used with the Personalization server, do the following:

  1. Install PersSample.ear
    1. Start the IBM WebSphere Application Server V4.0 AE Administrator's Console
    2. Right-click the Enterprise Applications folder and select Install Enterprise Application
    3. Verify that the Install Application (*.ear) radio button is selected
    4. Type the Path (or Browse) for the PersSample.ear file included on this CD
    5. Click the Next button to continue through the dialog and click the Finish button
    6. After PersSample.ear successfully installs, expand the Enterprise Applications folder, right-click Personalization Sample, and select Start
    7. Expand the Nodes folder, right-click your node, and select Regen Webserver Plugin
    8. Restart the Application server

  2. Create the datasource for PZNDEMO
    1. In the Administrator's Console, expand WebSphere Administrative Domain -> Resources-> JDBC Providers-> Pers DB Driver
    2. Right-click the Data Sources folder and select New...
    3. In the Data Source Properties dialog, select the General tab
    4. For the Name, type pzndemo
    5. For the JNDI name, type jdbc/pzndemo
    6. For the Database name, type PZNDEMO
    7. For the User ID, Password, and Confirm password, type a user ID of wsdemo and a password of wsdemo1
    8. Click OK

  3. Use your Web browser to access the Personalization YourCo Toys sample located at http://<host_name>/PersSample/index.html and follow the link to "Create the PZNDEMO Database here"

 

To install the sample to be used with the Personalization workspace, do the following:

  1. Install the PersSample.ear as described above
  2. Add the PersSample project to the Personalization workspace
    1. Login to the Personalization workspace (http://<host_name>/PersWorkspace/index.jsp)
    2. Click on Global Settings -> Manage Projects -> Add Project
    3. Check the Open existing radio button
    4. Type the Project Path, for example C:\WebSphere\AppServer\installedApps\Personalization_Sample.ear\PersSample.war\personalization\projects
    5. Under Project Name, select PersSample
    6. Click OK
    7. In Manage Projects, select PersSample in the list and click Make Current
    You will now be able to view the components of the sample in the Personalization workspace.

 

To install the sample to be used with both the Personalization server and workspace, do the following:

  1. Install the PersSample.ear as described above
  2. Use your Web browser to access the Personalization YourCo Toys sample located at http://<host_name>/PersSample/index.html and follow the link to "Create the PZNDEMO Database here"
  3. Add the PersSample project to the Personalization workspace as described above.
  4. Add your preview server to the PersSample project.
    1. Click Edit Project
    2. Under Preview Server, select the name of the server from the drop-down list (you may have to add the server, if it has not been previously defined)
    3. Click Save

It is not necessary to publish the sample files. You will now be able to preview the sample in the Personalization workspace.

 

Accessing the sample

Use your Web browser to access the Personalization YourCo Toys sample located at http://<host_name>/PersSample/index.html (where <host_name> is the name of the server on which PersSample was installed). Before using the sample, you will need to configure the PZNDEMO database. Instructions for configuring the PZNDEMO database are linked from the YourCo Toys sample index.html page.

 

Uninstalling WebSphere Personalization

To uninstall WebSphere Personalization from an application server:

  1. Ensure that the Administrative Server for the target application server is running.
  2. If you are running the uninstall program on an AIX system, ensure that the display resolution is not higher than 1024x768.
  3. To start the uninstall program:
  4. The uninstall program offers you the option to drop the Personalization database tables.
  5. After the uninstall is finished, exit the program.