Introduction

IBM ® WebSphere® Personalization 4.0 lets WebSphere Application Server developers create and deploy customized Web pages that meet the interests and needs of specific users. For example, an online book retailer can supply a Web form from which a user can select categories of interests. Then, each time the user logs on to this book store site, the site would display new books related to the specified interests. WebSphere Personalization allows personalization rules to be managed independently from the rest of the application code. Therefore, personalization rules can be easily applied to multiple applications and be managed by the most appropriate people: non-programmer business users who best understand the business.

A complete discussion of what personalization is and how it is used is a separate topic and will not be discussed in-depth in this article. For more information on personalization itself, see the Resources section. The purpose of this article is to provide step-by-step instructions on how to create a sample Personalization 4.0 application using rules and resources. The primary focus of WebSphere Personalization is to customize Web page content. However, personalization rules can be used for other purposes. For example, content selected by a personalization rule does not always have to be displayed; it can be used to specify a view, an aspect of a view (such as color or font used in a JSP), or even program logic choices to be used. Because most existing Personalization documentation use examples of content customization, and various customers have been interested in other usage scenarios, the sample selected for this document uses a personalization rule to customize the view (that is, the JSP page) displayed back to the user.

Back to top

Overview

Application developers would carry out the following tasks:

1. Create a front-end Web application using JSPs and/or servlets. Define at least one JSP that will use personalization.
2. Define one or more user resources that define attributes of a user (typically from a database or LDAP resource but can be any resource) that you want to use in business rules.
3. Define content resources that specify attributes (typically within one or more database tables and columns) whose values you want displayed based on a business rule.
4. Define content spots that define where certain personalized content should go. Drag and drop them into JSP pages where you want that content based on a business rule to go.
5. Package/publish all application files and deploy them on WebSphere Application Server.

To carry out the above, application developers can choose any of the following three methods:

• Use WebSphere Studio 4.0 Professional Edition and the personalization wizards for Studio 4.0 Professional Edition that are available when WebSphere Personalization 4.0 is installed.
  
  
• Use the APIs defined in the WebSphere Personalization InfoCenter to generate the same code that the wizards create. This method requires much more effort, but the way it must be done if user/content resources must be generated using data stored in other places is not yet supported by the wizards. At the time of writing, the wizards support the following data resources:
• Specified types of databases
• Specified types of LDAP repositories
• Enterprise Information Portals 7.1 support is available in the content wizard if the EIP 7.1 client has been correctly configured on the plugin. Refer to the readme shipped with the WebSphere Personalization wizards for WebSphere Studio Application Developer 4.0 for information on configuring the wizards for EIP.
  
  
• Use WebSphere Studio Application Developer and the available wizards. Application Developer is now the recommended tool for carrying out the above tasks. This article, as indicated in the title, follows this method.

Then, a non-technical business user can define personalization rules using the Personalization Workspace that is accessed by a browser: http://localhost/PersWorkspace/index.jsp. There are several types of personalization rules. A rule can be a:

• Classifier - Defines classifications that a user will be categorized within if given conditions hold true on user attributes.
• Action - Defines an action. Valid actions at this time are selected. Or, you would modify data from a content resource.
• Binding - Binds action(s) to classifier(s) so that a certain action takes place if a classifier holds true on the user that is currently logged in.

Note a terminology change between WebSphere Personalization, Version 3.5 and Version 4.0: the term "rule" used to refer to only a binding rule, but now classifiers and actions are also described as types of rules.

Classifiers, actions, and bindings can be used individually or together. For example, a classifier might be used by itself if the only thing you want the business users to do is to be able to create and modify the definitions for given classifications to be used in an application. Another example: an action might be used by itself if you only want a business user to be able to define and/or change what action to perform in a given application situation that you have described to the business user. The example in this document will demonstrate a very common combination of rules: a classifier will be created to classify users, actions will be defined for each classification of user, and a binding rule will be created to determine which action is performed for which classification of user.

Back to top

Prerequisites

To walk through this tutorial, you need to have the following installed on your system. It is important that you have exactly the same software on your machine:

• DB2® Universal Database, Version 7.2 and fixpack 5
• HTTP Server, Version 1.3.19
• WebSphere Application Server, Advanced Edition, Version 4.0.2 (Note that you must install the Advanced Edition, not the Advanced Single Server Edition.)
• WebSphere Studio Application Developer, Version 4.0.3 and shortcut key update for 4.0.3
• WebSphere Personalization wizards for Application Developer 4.0
• WebSphere Personalization 4.0 and fixpack 1

Install on a single machine and in the order listed above. Complete the following:

1. Download fixpack 5 for DB2 from the DB2 support Web site. You must apply fixpack 5 because it is required by WebSphere Application Server 4.0.2. See the Application Server requirements at the Product Overview Web site. Click Library, and then click on the link for the hardware/software requirements.
   
   
2. Install DB2 7.2, DB2 fixpack 5, HTTP Server, and WebSphere Application Server as described in the installation guide for Application Server, which can be accessed online at the Product Overview Web site. Click Library in the left-hand menu, then click on the link for the InfoCenter at the top of the page and choose to view the online version of the document. You will need to have a Java^TM-enabled browser. In the online version of the InfoCenter, click Contents => Installation, and use the installation guide for Windows® for the HTTP Server and DB2.
   
   
3. Download fixpack 2 for WebSphere Application Server from the WebSphere Application Server Support Web site. Click Support in the left-hand menu. Fixpack 2 can be applied to WebSphere Application Server, Version 4.0 or 4.01 to bring it up to the 4.0.2 level.
   
   
4. After installing WebSphere Studio Application Developer:
   1. Install the latest fixpack for WebSphere Studio Application Developer by going to the Product Overview Web site. Click Support in the left-hand menu to check for fixpack downloads. At the time of writing, there is a shortcut key update for 4.0.3.
      
   2. Download and install the Personalization wizards using software and installation instructions from the WebSphere Personalization Web site. Click Downloads in the left-hand menu.
      
      
5. Install WebSphere Personalization 4.0, noting the following:
   • The installation guide for WebSphere Personalization 4.0 is the following file in the root directory on the Personalization 4.0 CD: PZNINSTL_en.HTM. You should read the installation guide and readme for Personalization 4.0 before continuing. At the time of this writing, the installation guide requires that whatever database you choose to use for Personalization tables be created before the installation.
   • WebSphere Application Server 4.0.2 already contains the APAR 51952 fix that the Personalization installation readme says is necessary.
   • This example assumes a single node is used for development and test, so all Personalization components were installed on the same box while WebSphere Application Server was running on the box (required to install the Personalization Server). Note that you do not need to install the earlier WebSphere Studio Version 4.0 wizards since the WebSphere Studio Application Developer wizards are used instead.
   • The installation process will require that you specify an application server to install Personalization into; this example assumes Personalization is installed into the Default Server that installs as an example application server during WebSphere Application Server installation.
   • When installing the Workspace component, specify the user ID to be administrator.
     
     
6. Install the latest fixpack for Personalization 4.0 by going to the WebSphere Personalization Web site, and click Support in the left menu to check for fixpack downloads. You may have to click on More in the support downloads section to find fixpacks. At the time of writing, Personalization fixpack 1 was available.
   
   
7. If you want to see the Personalization sample demo provided with the product, follow the instructions in the PZINSTL_en.HTM installation guide mentioned above.

Back to top

Build the sample application

We will create a sample application called myProject. This application will have a login page for the user to enter a user ID. The user ID will then be used by a personalization business rule that looks up the user's organization type in a database and decides which JSP page to display to the user based on the organization type. This sample application assumes that the reader is familiar with WebSphere Application Server, and with basic WebSphere Application Server administration, HTML, JSP, and servlet technology. A basic understanding of WebSphere Studio Application Developer is also helpful.

Note that <was_root> refers to the full directory path where WebSphere Application Server is installed. The default installation root for Application Server on Windows is c:\WebSphere\AppServer.

Decide the data to be used in the personalization rules

This sample will create the following:

• A user resource defining data used to classify users/conditions under which to execute action rules.
• A content resource that defines data to be displayed (via an action rule).

You can use the Personalization APIs to create your own user and content resources that retrieve data from anywhere. However, the easiest way to define user and content resources is to have the data in a place that is supported by Personalization wizards that will create user and content resources (implementing the APIs) for you. Therefore, we will use DB2 database tables to store information for both. See Appendix A in the file available for download below for the DB2 script that we will run to create the database. Use the directions contained in the script as comments for running the script. The script creates a new database with the following two tables owned by a user called db2admin:

• Users - A table that contains two users called mickey and donald. We will use the organizationType column in this table in our business rule to determine which JSP layout will be displayed to certain users.
• Layouts - A table that defines the possible layouts that can be displayed to a user: layout1.jsp and layout2.jsp.

Create a WebSphere Studio Application Developer project

1. Start WebSphere Studio Application Developer.
2. Create a new project by selecting File => New => Project => J2EE => enterprise application project.
3. Click Next. The Enterprise Application Project dialog opens. In the Enterprise application project name field, enter myProject. Under Which additional module projects would you like to create?, select Web project name. Ensure that Use default location is also selected on this screen.
4. Click Finish. Before going any further, it is recommended that you read the help information on Personalization features that are added by the wizards you installed into Application Developer. Select Help => Help Contents => Concepts => Personalization. Also, read all of the sections under Help => Help Contents => Tasks => Using Personalization.
5. The help documentation referred to above tells you how to change the default location for rules, resources, and source files if desired; this project will use the defaults so no extra work is necessary.
6. Enable BeanInfo introspection for your project. First, select Perspective => Open => Web to get to the Web perspective. Right-click the myProjectWeb project, and select Properties => BeanInfo Path. Then, select Enable BeanInfo Introspection on this Project. Click OK to finish. If introspection is not enabled, then properties of the bean may be incorrectly listed in the Page Designer dialogs.

Create a Web application to be personalized

1. Go to Appendix B in the file available for download with this article, and import the application files as instructed.
   
   
2. Your Application Developer project should now show the following files in the Navigator pane. See Figure 1 below.
   Figure 1.
   
   
3. If you see a Tasks window as displayed above, don't worry if you get a "servlet/JavaServlet-Broken Link" message; the servlet mapping created when setting up JavaServlet.java (see Appendix B in the file available for download with this article) will take care of this link. You can always verify that you have this link by double-clicking web.xml, and selecting the Servlets tab below the web.xml screen to see the servlets and servlet mappings defined.
   
   
4. Since WebSphere Application Server security is not used in this sample, we need to explicitly define the currently logged-on user by setting a special personalization parameter called pzn.userName in the session to the name of the user accessing the site. We can get this from our login page that prompts for a user ID. This step has already been done for you in the sample JavaServlet.java file. Open this file (by double-clicking it in Application Developer), do a search on the word pzn, and examine the code that sets the pzn.UserName parameter. Now, select File => Close to close the file. For more information on the pzn.userName variable, go to the WebSphere Personalization InfoCenter and do a search on pzn.userName.
   
   
5. Click myProject, and select rebuild Project.

Create user and content resources

Now, we will start the process of adding personalization to the application we just set up. Create user resources using the user resource wizard:

1. Still within the Web perspective, highlight the webApplication folder within the myProjectWeb project in the left pane of the Navigator window.
   
   
2. Since you have installed the WebSphere Personalization 4.0 wizards for WebSphere Studio Application Developer during the installation section of this document, you should have three personalization icons in your menu bar. Hover over the circle with two people in it and you will see that it is the icon for the personalization User Wizard V4. Click on this icon; User Wizard V4 opens to the Welcome page.
   
   
3. Click Next. Now on the login page, complete as follows:
1. In the Protocol field, select Database (SQL).
2. In the Database URL field, enter jdbc:db2:myProj.
3. In the User ID field, enter db2admin. Note that the password field is set to db2admin.
4. In the Driver location field, ensure that C:\SQLLIB\java\db2java.zip is selected.
5. In the Driver identifier field, select IBM DB2 UDB local.
6. The Driver class and DataSource class are already selected for you.
   
   Note that Version 4.0 of Personalization also has an LDAP option in the protocol drop-down menu. You can always come back later and try using LDAP instead of a database to define resource attributes for your users, but try this exercise as-is for now.
   
   
4. Click Connect. The tool connects to the myProj database that was created in the steps above. On the next screen, click Users and the > button to select the users table. Your screen will now look like Figure 2 below.
   Figure 2.
   
   
5. Click Next. The following screen shows all of the columns in the user table. Select both columns by selecting the first column and then pressing the <Ctrl> button while you click the second one. Then, click the > button to move both columns to the selected columns area. Your screen should look like Figure 3 below.
   Figure 3.
   
   
6. Click Next.

   Note: In Version 4.0 of Personalization, you can select more than one table on the first screen and join data from multiple tables on this screen. But we will not need to do any joins in this example. You can always come back later, and continue clicking Next to take a look the remaining tabs.

7. Click Finish. You should now see a new user resource in your Application Developer project. The new user resource called Users shows up as the following new files defined by the Personalization API:
• Resources\Users.hrf - Defines the resource class hierarchy.
• myProjectWeb\source\Users.java - Has getter/setter methods for each column attribute you selected for your resource.
• myProjectWeb\source\UsersBeanInfo.java - Java Bean Info file for the Users class.
• myProjectWeb\source\UsersManager.java, myProjectWeb\source\UsersManagerAuthor.java - Implements personalization API methods for populating/managing the data (through JDBC calls) within your users resource.

  Each of the above Java file has a corresponding class file under myProjectWeb\webApplication\WEB-INF\classes.

8. Your project should display the above files in the Application Developer Navigator pane. You may want to open each of the files generated by the resource wizard (described above) to briefly examine the contents. Refer to the WebSphere Personalization documentation on the Personalization API for more details on these files.
   
   
9. Now, create a content resource using the content resource wizard. Click on the webApplication folder within the myProjectWeb project.
   
   
10. Then, hover over the personalization icon in the menu bar; notice that it is the icon for the Content Wizard V4. Click on this icon.
    
    
11. On the Welcome page, click Next. The next screen should look familiar to you. The procedure for creating a content resource is exactly the same as for creating a user resource. Fill in this screen exactly the same as you did for the user resource above, and click Connect.
    
    
12. Once you are connected, select the layouts table on the next screen, and click the > button to move this table to the selected tables area. Then, click Next. The following screen lets you select table columns.
    
    
13. Select all of the columns in the layouts table, and click the > button to move them to the selected columns area. Click Next.
    
    
14. Now, click Finish. After the content resource that you just defined is created, you should see files similar to the ones that were created for your users user resource. You should see a new layouts.hrf under the resources folder, and also see new Layouts, LayoutsManager, LayoutsManagerAuthor, and LayoutsBeanInfo Java and class files.

Create a content spot

Create a content spot on a JSP page to define where a business rule will be applied:

1. Click webApplication in the hierarchy of folders in the Navigator window in the left pane.
2. Click the icon in the menu bar for the personalization Content Spot Wizard V4. The Content Spot Wizard opens to the Welcome page.
3. Click Next. The Rule Type page opens. For the Content Spot Java Bean, specify and name of LayoutChoiceContentSpot. Then, specify that you want the content spot to represent a business rule that will select content from our Layouts content resource: from the Choose a resource drop-down menu, select Layouts.
   
4. Click Next to see the file that will be created for you, and then click Finish.
5. You will now see that a Java file and the corresponding class file by the name of LayoutChoiceContentSpot has been created, as shown in Figure 4 below.
   Figure 4.
   
   
6. Apply the content spot that you just created to the ChooseLayout.jsp file:
1. Double-click ChooseLayout.jsp to open it. Important! Be sure to click on the Design tab located just below the window displaying ChooseLayout.jsp to get it into design view, which shows the content that the JSP will display in a browser.
2. Drag and drop the content spot, LayoutChoiceContentSpot.class, onto the JSP file at the location just before the text: Put your text here. Now, you will see Figure 5.
   Figure 5.
   
   

   Notice the choices in the Scope drop-down menu. When you create a content spot, you would normally make your selection based on whether your application will need the content selected by your business rule for just the current page, the request, session, or application. Refer to the servlet API for more information on the above types of scopes. You may want to make a note to come back and read about the setProperty and JSPtags tabs in the documentation.

7. Click Add, and then click OK to finish.
8. Now, click on the HTML Source tab of your JSP file. Notice that applying the content spot simply added the following to your JSP:

   <jsp:useBean class="LayoutChoiceContentSpot" id="layoutChoiceContentSpot"> </jsp:useBean>

   
   

   The above line will cause the JSP to have access to content populated in the LayoutChoiceContentSpot bean by personalization once we have defined a business rule. We will be doing this soon.

   At the time of this writing, the readme file for the Personalization Wizard for WebSphere Studio Application Developer says that you have to explicitly call setRequest(request) when you add a content spot to a JSP. Therefore, add the line in bold after the useBean line, as shown:

   <jsp:useBean class="LayoutChoiceContentSpot" id="layoutChoiceContentSpot"> <% layoutChoiceContentSpot.setRequest(request); %> </jsp:useBean>

   
   

Add any other code that needs to use personalization content

Now, we will finish the ChooseLayout.jsp page by making use of the content that we have just given the JSP access to:

1. In the HTML Source view of the ChooseLayout.jsp page, remove the text put your text here, and replace it with a blank line. Click to place your cursor at the start of this blank line.
   
   
2. Open the LayoutChoiceContentSpot.java file and you will see that you should call the getRuleContent() method to get access to content returned from a content spot (refer to the Personalization API help documentation as needed). When we earlier created our content spot in the JSP, we specified that we wanted the content spot to return the Layouts content resource and we can see that our content spot's getRuleContent() does indeed return a layout/set of layouts. The Layouts content resource will contain specific values for a given user based on a business rule that will soon be defined. We want to use the JSPFILE attribute (the name of a JSP page) of the Layouts content resource in an include statement since we want to display this given JSP, chosen by the business rule, back to the user. Therefore, we add the line in bold below to get access to JSPFILE. Add the rest of the code required to perform a JSP include of the JSPFILE returned by the content spot so that your JSP looks like the following:

   <!-- Sample JSP file --> <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> <HTML> <HEAD> <TITLE> Put Your Title Here </TITLE> </HEAD> <BODY BGCOLOR="#FFFFFF"> <% String layoutToUse; %> <jsp:useBean class="LayoutChoiceContentSpot" id="layoutChoiceContentSpot"> <% layoutChoiceContentSpot.setRequest(request); %> </jsp:useBean> <% layoutToUse = layoutChoiceContentSpot.getRuleContent()[0].getJSPFILE(); %> <jsp:include page='<%=layoutToUse%>' flush="true" /> </BODY> </HTML>

   
   
3. Double-check that your JSP looks exactly like the source above to avoid having to debug later.
   
   
4. Note that the above shows the following changes performed:
• A string called layoutToUse was defined.
• The layoutToUse string was set to the return value of getJSPFILE that was added above.
• Then, layoutToUse is used as a substitution variable defining a JSP in a JSP include statement.

  Here is additional detail about what we have just accomplished:

  When we defined our content spot above, we defined it to be populated with content from our layouts content resource. The whole purpose for the content spot is to allow a business user to define a rule (which we will soon create) to populate this content spot with data from the layouts resource. The data in particular that we want to use is the JSPFILE attribute of the layouts resource. Therefore, according to the Personalization APIs defined in the Personalization documentation, we will want to call the method getRuleContent() to get an array of resources returned from this content spot, then call the getJSPFILE method on the first resource returned (the 0th element in the array of results). Note that if you were deploying this code, you would probably also want to check that the array had at least one element before referring to the array's first element. The code above depends upon your rule returning at least one resource; otherwise, an ArrayIndexOutOfBoundsException may be thrown.

5. Select File => Save to save the JSP we have just modified, and then select File => Close to close it.

Package the application as a standard J2EE application

At the time ef writing, WebSphere Personalization 4.0 is only supported in the Advanced Edition of WebSphere Application Server, but WebSphere Studio Application Developer only supports the Advanced Single Server Edition of WebSphere Application Server for remote testing. This will soon change, but for now, follow the instructions in these next few sections to package, deploy, and test your application.

1. Highlight myProject in the Navigator window in the Web perspective.
2. Select File => Export, and then select EAR file. The EAR Export page opens. On this screen, under What resources do you want to export?, select myProject. Under Where do you want to export resources to?, select the location of your myProject.ear file. In this sample, we use: C:\tempPers4Files\myProject.ear. Click Finish.

Back to top

Deploy the application on WebSphere Application Server

1. With WebSphere Application Server and the Administrative Console up and running, right-click Enterprise Applications in the Administrative Console, and select Install Enterprise Application from the drop-down menu.
   
2. Fill out the next screen as follows, ensuring that you use the correct case for the names. In the Browse for file on node field, I've entered mpike. Select the radio button Install Application (*.ear), and then in the Path field, enter C:\tempPers4Files\myProject.ear, and in the Application name field, enter myProject.
   Figure 6.
   
   
3. Click Next until you get to the screen below. Here, choose to install into the default_host. See Figure 7 below.
   Figure 7.
   
   
4. Then, click on the Select Server button, and then select the Default Server in the next screen, as shown in Figure 8.
   Figure 8.
   
   
5. Click Finish. You should see a message that your application installed successfully; click OK to close this message window.
6. Now, restart the default_server. Right-click default_server and choose to stop it. Then, when you get a pop-up message indicating that the server has stopped, right-click default_server again and choose to start it. Click OK on the message window indicating that the server is started.
7. Then, regenerate the configuration information for the Web server plugin by right-clicking the name of your node, and selecting Regen Webserver Plugin from the drop-down menu.

Back to top

Publish and load personalization files

Although personalization files were included in the files that we just packaged and deployed into WebSphere Application Server, additional steps are required to load the personalization features. There are two ways to publish and load personalization features:

Method 1: Publishing personalization resources through an Application Developer publishing server

The following tip on this method is provided for interested parties but the focus of this document is on method 2 below since method 1 will be a better solution in a future release.

At the time of writing, the only remote server Application Developer supports is the WebSphere Application Server, Advanced Single Server Edition, which Personalization is not supported on. However, you can still set up a remote server for WebSphere Application Server, Advanced Edition to be used for publishing (as opposed to testing).

1. Set up a server instance and configuration as already documented in the Application Developer documentation.
2. Select Windows => Preferences => Server, and set the publishing method to prompt user.
3. Double-click your server configuration, and set the HTTP Transport Port to 80.
4. After you have added myProject to your server configuration, right-click the server that you created in the servers window and select Publish. You will know if the resources got published successfully by checking the Personalization Resource Console: http://localhost/PersAdmin/adminframe.jsp. If you see your resources listed there, then the publish was successful. Note that localhost is where WebSphere Application Server is running.

Method 2: Using personalization prznload

Copy all of the resource files (*.hrf) to: <was_root>\personalization\publishedResources. One place to get a copy of the *.hrf files is where myProject was installed into WebSphere Application Server:

<was_root>\installedApps\myProject.ear\myProjectWeb.war\resources

Now, load personalization resources. It is strongly recommended that you run the following URL to make sure that WebSphere Application Server and WebSphere Personalization is up and running before you continue:

http://localhost/PersAdmin/adminframe.jsp

If this URL successfully loads, then continue. Otherwise, contact your WebSphere Administrator to make sure that the Administration Server and WebSphere Personalization are running.

Using pznload:

1. Unzip pznload.zip from your Personalization 4.0 CD into a temporary directory called c:\tempPers4Files\pznload, and follow the instructions. The instructions are summarized for you in the steps below:
2. Go to c:\tempPers4Files\pznload and create a file called pznResourcesToLoad.txt that contains one line per resource file that specifies its path and filename relative to <was_root>\personalization\publishedResources. For our example, this file would contain only the following two lines:

   Users.hrf Layouts.hrf

   
   
3. In the same directory, run the following command (note that both copies of c:\WebSphere\AppServer should be replaced with your WebSphere Application Server installation directory if the default was not used):

   pznload localhost c:\WebSphere\AppServer -verbose -logfile c:\WebSphere\AppServer\logs\pznloadLog.txt

   
   

If you have trouble using pznload for any reason, follow the alternative below:

1. For each Personalization Resource (*.hrf file) that you copied to the <was_root>\personalization\publishedResources directory above, run the following URL in a browser (replace <was_root> and <resource hrf file> as appropriate):

   http://localhost/PersAdmin/servlet/com.ibm.servlet.personalization. ImportExport.ImportServlet?filename= <was_root>\personalization\publishedResources\<resource hrf file>

   
   
2. If WebSphere Application Server is installed on your localhost under c:\WebSphere\AppServer, then for the example in this article, you would need to run the following two URLs:

   http://localhost/PersAdmin/servlet/com.ibm.servlet.personalization. ImportExport.ImportServlet?filename= c:\WebSphere\AppServer\personalization\publishedResources\Users.hrf http://localhost/PersAdmin/servlet/com.ibm.servlet.personalization. ImportExport.ImportServlet?filename= c:\websphere\AppServer\personalization\publishedResources\Layouts.hrf

   
   

Be sure to remember that each time you make changes to your project:

• You must deploy the application changes to WebSphere Application Server as you would for any other Application Server application. Refer to the WebSphere Application Server InfoCenter for when changes would require a restart of the application server and when they would not. Most of the time, you can simply copy new or modified files to the appropriate location in the <was_root>\installedApps\myProject.ear\myProjectWeb.war directory, and add any new definitions for servlet mappings to the <was_root>\installedApps\myProject.ear\myProjectWeb.war\WEB-INF\web.xml file so that new servlets can be found. JSP changes may require you to remove old compiled versions of these JSPs under <WAS installation directory>\temp to force a recompile or reload of the new JSPs.
• If the name or contents of the .hrf file for a user/content resource changes, you must republish it by completing the steps above.

Back to top

Document personalization features

Now, the developer should document all personalization features that were earlier created: the name and description of each user resource, content resource, and content spot, and the directory path where the Web application archive (.war) file is installed in WebSphere Application Server (<WAS installation directory>\installedApps\myProject.ear\myProjectWeb.war). This documentation should be forwarded to the project members who will be defining the business rules.

Set up project in workspace for personalization rules

1. Make sure that WebSphere Application Server, Advanced Edition, Version 4.0 is up and running.
2. Make sure that the application server you installed WebSphere Personalization into is up and running; this example assumes that you have installed Personalization into the Default Server.
3. Bring up the Personalization 4.0 workspace by entering the following in a browser: http://localhost/PersWorkspace/index.jsp, where localhost can be replaced with the host that WebSphere Application Server is running on.
4. Sign in with the user ID you specified when you installed the WebSphere Personalization workspace. See Figure 9 below.
   Figure 9.
   
   
5. Then, click the Global Settings button. The Personalization Global Settings - Manage Projects page now opens. If you do not see this screen, click Manage Projects from the menu list on the left to get to the screen.
   
   
6. Click the plus sign (+) icon on the right-hand side to add a new project. Complete the fields of the Add Project dialog, as follows:
1. Click the Create new radio button to create a new project. Specify the project path to be the path where you published your Studio resources to:
   c:\WebSphere\AppServer\installedApps\myProject.ear\myProjectWeb.war, where c:\WebSphere\AppServer\ is the directory where WebSphere Application Server is installed on your particular machine.
2. Set the name of your project to match that of the Studio project: myProject. The screen should look like Figure 10.
   Figure 10.
   
   
7. When finished, click the OK button. Be patient as it may take a few moments for it to finish saving.
8. The Edit Project dialog now launches. Make the following changes:
1. Click on the path shown for Resource Paths, and then add the following to the end of the path: \resources. Make sure to click the + icon to add this new path to the resource path since this is where our resources were placed.
   
2. In the Resource and Content Spot Class Path field, and add the following to the path specified: \WEB-INF\classes.

   The screen should look similar to Figure 11 (but with c:\WebSphere\AppServer replaced by your own directory path to where WebSphere Application Server is installed).

   
   Figure 11.
   
   
9. Do not change anything in this initial sample. You may want to click on one of the underlined properties to read the descriptions of each field in case you want to modify one of the fields after you get this sample running.
10. Click Save when you are ready to continue. It may take a few moments for it to finish saving.
11. Back on the global settings window, highlight your project, and click the Make current button to make it the current project. Click Close to return to the main Workspace window.

Define personalization rules

1. Click the Rule Composer tab. It is common to create three types of rules:
• The first type of rule you normally create is a classifier which will group users into classifications. In our case, we will classify users who have an organization type of bank to be in a banking classification, and all other users to be in a classification of other.
• Then, create an action to describe the action that the personalization rule will perform (the type of content to retrieve or update from a content resource created in Application Developer). In our case, the action will retrieve the name of a JSP file from our Layouts content resource created in Application Developer. Refer to steps that we performed in Application Developer to recall that the JSP retrieved will be used as the next page to display back to the user.
• Finally, create a binding rule to bind an action with a classification: in our case, we will bind the action of retrieving a particular JSP page for banking users and the action of retrieving a different JSP page for any other types of users.
  
  
2. In the left pane, you will see a drop-down box of rule types. Select classifier.
3. You should now see your project War file in the left pane. If you do not see your project War file in the left pane, go back into global settings and review the steps above to ensure that your settings are correct and that your project is set as the current project.
4. Click the + icon in the top left to add a new classifier.
5. In the next screen, enter the name of your classifier: OrganizationClassifier.
6. Enter the comment about the classifier: Determines if a user is from a bank.
7. Now, we define the rule by clicking on each underlined word in the rule template one at a time: first, click on the underlined classification. In the next screen, enter the classification as banking. Click Save.
8. Now, click on Resource.Attribute. On the next screen, click to select the resource as current Users (not current user session), and ensure that the attribute selected is Organization_type. If you do not see current Users as a choice in the screen, then most likely the publishToWorkspace publishing stage in Application Developer was not set up correctly, and you will need to correct the problem and republish in order to complete this step.
9. Click Save.
   
10. Click on the underlined value. On the next screen, ensure that the Specify a value of type text radio button is selected. Enter the value as bank.
11. Back on the Add Classifier screen, click on the underlined classifier that comes after Otherwise. On the next screen, enter: OtherOrganization. Click Save. Now, back on the Add Classifier window, you will see Figure 12.
    Figure 12.
    
    
12. It is important to note that current Users in the rule above refers to the user resource called Users that we created in Application Developer. This uses data from the Users table in the database. At run time, current Users will be automatically populated with data for the row in the Users table that has a primary key (user ID) that matches the special personalization attribute called pzn.userName that we set in our servlet in the previous step.
13. We are now finished with this classification rule so click the Save button.
14. Now, select Actions from the drop-down box of rules you can create within the workspace.
15. Click the + icon to add an action rule.
16. On the next screen, give your rule the following name: DisplayBankScreen. There are two types of actions you can select from the drop-down box: Select content or Update (that is, update the content in the database). Choose Select content.
17. Click on the underlined Resource.Attribute. On the next screen, select the resource to be Layouts and the attribute to be LAYOUTDESCRIPTION. Click Save.
18. Click Value. On the next screen, enter the value to be layout for banks (this is one of the layout descriptions in the database tables that we earlier set up using the script in Appendix A -- see the file available for download below). Click Save. Your finished rule should resemble Figure 13 below.
    Figure 13.
    
    
19. Repeat the steps above to create another action that looks like Figure 14.
    Figure 14.
    
    
20. Back on the main Workspace window, select Bindings from the drop-down box of rules and click the + icon to add a binding rule.
21. On the next screen, enter the name of the binding rule: DisplayScreenForOrganizationClassifier.
22. Click on the underlined Classifier. On the next screen, make sure that the OrganizationClassifier radio button is selected, and click Save.
23. Click the underlined Classification. On the next screen, set the classification to banking, and click Save.
24. Click do Action, set the action to DisplayBankScreen, and click Save.
25. Click do Action under Otherwise, and set the action to DisplayDefaultScreen. Click Save. Your completed binding rule should look like Figure 15 below.
    Figure 15.
    
    
26. Save your finished binding rule.

Back to top

Apply rules to application content spot

Now, add your rule to a content spot within your Web application by completing the following steps:

1. Click the Campaign Manager tab. Under the Campaign Manager tab, make sure that Web site is selected.
2. In this example, we will not be creating any campaigns that describe seasonal events, etc. when you want to modify your site. Our personalization rule will instead be applied to the normal view of our Web site, so you should click on Normal View in the left pane.

   Note: If you only see Priorities and Normal View under the Campaign Manager tab, then you do not have any campaigns. If you want to assign a rule to a content spot that is associated with a campaign, then you will need to create a campaign (try this later if you wish).

3. In the right pane, you should see the LayoutChoiceContentSpot that we earlier created in our Application Developer project that was associated with this workspace project. Click the empty link under the Rule column. The Fill Content Spot dialog now opens in a new window.
4. From the drop-down list of the Fill Content Spot dialog, select our binding rule, DisplayScreenForOrganizationClassifier:
   Figure 16.
   
   
5. When finished, click OK. Notice that once a rule is chosen, the above screen will then show choices to remove or edit the rule.

Back to top

Publish the rules

1. Define a server to publish to by completing the following steps:
1. Select Global Settings => Manage Publish Servers.
2. Click the + icon to add a publish server. The Add Publish Server page opens.
3. On this screen, in the Name field, enter myServer. In the URL field, enter http://localhost. Note that we do not have security enabled in this example. Click Save.
   
   
2. Now, still within global settings, publish your rules by completing the following steps:
1. In the left pane, click Publishing files.
2. Select your publishing server and publishing method from the drop-down lists. You have the option to publish all files or publish only modified files. Choose Publish All from the drop-down list.
3. Click the Publish button. If your publish is not successful, then the application server with personalization is probably not available for some reason; speak to your WebSphere Administrator.
4. Click Close twice to exit.

Back to top

Test the application

1. Test the application by entering the following URL in a Web browser: http://localhost/myProjectWeb/Login.html

   You should see the following output in your browser.

   
   Figure 17.
   
   

   If you do not see the screen above, then go to the Troubleshooting section below.

2. Enter the user ID: Mickey (make sure you use the correct case and do not capitalize).
3. Enter the password: mouse (the password can actually be anything since our application does not check it).
4. Click Submit. You should now see the following layout1 screen displayed; our personalization rule in the ChooseLayout.jsp page will return the layout1.jsp page if the logged-on user is a user in a bank organization. Recall that the user Mickey has an organizational role of bank in the database tables set up by following Appendix A in the file available for download below. If you do not see the screen below, proceed to the Troubleshooting section below. Otherwise, continue with the steps below.
   Figure 18.
   
   
5. Now, run the same application with a different user to see that the personalization rule will display the other layout if the logged-in user is not from a banking organization. Rerun the URL: http://localhost/myProject/Login.html. Enter the user ID: Donald, and password: duck. Click Submit. The layout2 output is now displayed in your browser. See Figure 19 below.
   Figure 19.
   
   

Congratulations! You have successfully completed the tutorial.

Back to top

Troubleshooting

If you were not able to bring up the Login.html screen, verify the following:

1. Make sure that localhost is the name of the node where WebSphere Application Server is running.
2. Go to the WebSphere Application Server Administrative Console and click on the myProject application. Then, click on Web modules to verify that the context root is specified as myProjectWeb. Make sure that the case is correct for all names with myProject, ensuring that MyProject was not used instead.
3. Login.html should be the name of the starting HTML page in your Application Developer project. Make sure that you are using the correct case.
4. Go to <was_root>\installedApps\myProject.ear\myProjectWeb.war and make sure that you see the Login.html page there. If you do not see it there, then you did not perform the steps above correctly when packaging, deploying, and publishing the application.

If you were able to bring up the Login.html screen, but did not get the correct layout screen back when you entered a use ID and password, then:

1. Go to <was_root>\installedApps\myProject.ear\myProjectWeb.war and make a copy of the ChooseLayout.jsp file to save the original. Then, modify this JSP so that the personalization lines are removed or commented out and so the JSP simply has a line to include the layout1.jsp. Before re-testing, remember to remove the old cached versions of the JSPs under <was_root>\temp\<your hostname>\Default_Server\myProject\myProjectWeb.war. Run the application and make sure that the layout1.jsp comes up to verify that the basic application is working and isolate the problem to the personalization part.
2. If the above test worked, then try making this change to see if the personalization part is working. Go to <was_root>\installedApps\myProject.ear\myProjectWeb.war and make a copy of the original ChooseLayout.jsp file and save it. Then, modify this JSP. Replace the following line:

   <jsp:include page='<%=layoutToUse%>' flush="true" />

   
   

   with these two lines:

   JSP returned by personalization is: <%=layoutToUse %>

   
   

   Before re-testing, remember to remove the old cached versions of the JSPs under <WAS installation directory>\temp\<your hostname>\Default_Server\myProject\myProjectWeb.war. Run the application. JSP returned by personalization is: layout1.jsp should be the output if personalization is returning the correct JSP.

3. From the WebSphere Application Server Administrative Console, click on the default_server where your application is installed. Then, in the right pane, click the JVM settings tab, then the Advanced settings button, and select the checkbox for turning on debug. Then, rerun the application and open the <was_root>\logs\Default_Server_stdout.log file with a text editor to see if there are any messages at the bottom that give you some information about what is wrong.
4. Review the steps in this article to correct any possible mistakes.

Back to top

Download

Name	Size	Download method
appendices.zip	4 KB	FTP|HTTP

Information about download methods

Resources

• WebSphere Personalization InfoCenter. This is installed (as an option) during installation. Once WebSphere Personalization is installed, access the InfoCenter by selecting Start => Programs => IBM WebSphere => Personalization => InfoCenter.
  
  
• Check the following Web sites regularly for updates:
  • The IBM WebSphere Personalization Web site will have the latest fixpacks and product documentation.
  • Redbooks Web site - Check for the latest relevant Redbooks. Search on personalization.
  • IBM WebSphere Application Server Web site
  • IBM WebSphere Studio Web site
  
  
  

About the author

Comments

Back to top

Trademarks  |  My developerWorks terms and conditions

Table of contents

• Introduction
• Overview
• Prerequisites
• Build the sample application
• Deploy the application on WebSphere Application Server
• Publish and load personalization files
• Document personalization features
• Apply rules to application content spot
• Publish the rules
• Test the application
• Troubleshooting
• Download
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Application Server
• Webcast: Using Rational Application Developer with WebSphere Application Server to increase productivity
• Briefing: Building SOA solutions and managing the service lifecycle
• Buy: WebSphere Application Server

My developerWorks community

Dig deeper into WebSphere on developerWorks

Rate a product. Write a review.

Write a review for Rational products today!

Special offers