Using the Catalog Application in a Portal

 

This chapter describes how to deploy your portal as a webapp, add e-commerce features such as site security and user authorization, use Webflow within a portal,and use pieces of the demo catalog application in a portal.

This topic includes the following sections:

• Deploying a Portal as a Webapp

• Using e-Commerce Functionality Within a Portal

• Using Webflow Within a Portal

• Reusing Pieces of the Demo Catalog Application in a Portal

Note: Throughout this chapter, the environment variable WL_COMMERCE_HOME is used to indicate the directory in which you installed the WebLogic Commerce Server 3.1 and WebLogic Personalization Server 3.1 software.

 

---

Deploying a Portal as a Webapp

To build a portal webapp using the Portal Framework, follow these steps:

1. In the %WL_COMMERCE_HOME%/server/webapps folder, create a new folder. Give it the name of your webapp. For this discussion, this new folder will be referred to as "Example" in the webapps folder.

2. Create a subfolder in your new webapps/Example folder called WEB-INF. In this folder put your web application's web.xml file.

   Note: If you do not already have a web.xml file, you may copy the one in webapps/admin/WEB-INF. You must remove the security-constraint and security-role elements from the document.

   If you are using tag libraries, copy the tag library descriptor files (*.tld) into the WEB-INF directory. Also copy the portal framework .tld files from portal/WEB-INF/*.tld.

3. Create a new file in your Example folder called index.jsp. In this file, put a JavaServer Page (JSP) forward to your portal home page:

   <jsp:forward page="/application/Example" />  

   where Example should be replaced by the name of your property set.

4. Open your weblogic.properties file found in %WL_COMMERCE_HOME% for editing. Search for the word "webapp." You will find a line beginning as follows:

   weblogic.httpd.webApp.wlcs=
   
   Copy this line and paste the copy below the original. Change the word "wlcs" to be the name of your webapp. There are two occurences of "wlcs", you must change both.

5. Start your WebLogic Commerce Server with WebLogic Personalization Server server by executing StartCommerce.bat found in %WL_COMMERCE_HOME%.

6. Log on to the Administration Tool. Navigate to the Property Set Manager.

7. Create a new property set. Give it the same name as your webapp. Copy properties from APPLICATION_INIT._DEFAULT_PORTAL_INIT. The property set type is "Application Init." Click Create and then Back.

   Click on the property set name to edit it. You will need to change the following properties:

   defaultdest = your portal's main page
   homepage = your portal's main page
   workingdir = /
   PORTAL_NAME = Example
   TTL = set low during development, then restore when deploying for service.

8. After you finish your changes, you must wait up to 5 minutes for the server to recognize the new changes. This time period is dictated by the TTL (time to live) property. Alternatively, you may eliminate this wait time by adding the parameter flowReset=true to any URL for your web application, which will cause the server to reload the property set.

9. Click Home, and then navigate to the Portal Manager.

10. On the Portal title bar, click the Create button. This displays a form that allows you to create a new portal.

11. For the portal name, enter the exact same text as you did for the PORTAL_NAME property in your property set. The rest of the form fields can be left as the default. Click Create to create your portal.

12. Test your site by opening a browser window and navigate to http://localhost:7501/Example where "Example" must match the name you gave to your web application in the weblogic.properties file in step 4.

You have successfully deployed your portal as a webapp.

 

---

Using e-Commerce Functionality Within a Portal

This section discusses the scenerio in which you want to have a portal as the entry point for your users, but also wish to build e-Commerce functionality into your application. An example of this case might be a portal with one portlet showing the user's shopping cart, another portlet allowing a search of the product catalog, and a third portlet showing the user's order history.

An immediate requirement of this type of site is that it be deployed as a web application. This is a requirement of the Commerce components, and therefore this requirement also applies to a portal that includes Commerce components. Before you can begin adding e-Commerce features to your portal, you must deploy your portal as a webapp. This involves a number of steps, including the creation of a web.xml file. For more information, see the previous section Deploying a Portal as a Webapp.

Once your portal is a web application, a major issue to consider is site security. The Portal Framework includes its own security model. Portal page security constraints are defined by personalization rules, the Portal Administrator tools, and the Portal end user personalization tools. The declaritive security model of J2EE is much too simplistic for a portal deployment. For instance, when a user who belongs to more than one group logs onto a portal, the portal needs to be able to query the user on which group to use for personalization. This query action cannot be implemented when declaritive security is employed. Therefore, when working with portals, you should avoid creating security constraints in the web application's web.xml file.

Another security issue is user authentication. When implementing your site, you will want single sign-on capabilities. To do this, the Portal Framework and Commerce features will share the login. To this end, the Portal Framework must perform the login request. Additionally, the Commerce features require the user's unified user type to be WLCS_Customer.

Finally, there are several configuration requirements when assembling your portal. This includes deploying your site as a web application, and also the use of a special Destination Determiner.

The purpose of this section is to guide you step-by-step through the issues discussed previously. As you proceed through the steps, a brief explanation is given. For a more thorough explanation of an individual step, consult the relevent documentation.

Follow these steps before employing Commerce features in your portal:

1. Deploy your portal as a web application. This process is described in the previous section.

2. Construct a single unified Application_Init property set. You must use the _DEFAULT_PORTAL_INIT template for your application initialization property set.

3. Establish a single destination determiner. The destination determiner to use is com.beasys.commerce.webflow.WLCSPortalDestinationDeterminer. It is capable of handling both WebLogic Personalization Server and WebLogic Commerce Server with WebLogic Personalization Server requests.

4. Establish a single destination handler. Establish this destination handler: com.beasys.commerce.foundation.flow.ServletDestinationHandler

5. Configure your portal main page as the application home page. The destination determiner is programmed to return the user to the home page if no destination information is included in the HTTP request.

6. Use _userlogin.jsp for User Authentication. The login page included in the Portal Framework is _userlogin.jsp. In order to satisfy the portal's security model, all logins must go through this JSP. This page performs the necessary method calls (setUser, setLoggedIn, and setSucessor) required by the portal security mechanism.

7. Ensure that the user has a unified profile type of WLCS_Customer. The Commerce functionality requires an extension to the basic user type. This extension is named WLCS_Customer, and is a unified profile type. Any user of your portal with Commerce features must have a type of WLCS_Customer.

8. Avoid declaritive security in your site. To reduce the complexity of the portal security model, try to avoid declaritive security in your site. Declaritive security appears as security constraints in your web application's web.xml file. This is not a necessary step, but it makes security management easier.

 

---

Using Webflow Within a Portal

In WebLogic Commerce Server with WebLogic Personalization Server, Webflow is a feature that allows you to string together JavaServer Page (JSP) files, input processors (IPs) and pipeline processors (PPs) without hard coding the linkage between them. Instead, the linkage is defined in an external Webflow properties file.

Something to consider is how Webflow works with portals. When using Webflow, your users are conducted through a number of complete JSP pages as they work through a process. The portal, on the other hand, generally keeps the user on a single portal page, while the contents of that page (the portlets) change state. Due to this difference, in the current implementation, you cannot use the Webflow feature of page transitions while you employ the Portal Framework. But you can utilize the power of input processors and pipeline processors from within a portlet. This section details how to do this.

The first requirement of Webflow is that your site must be deployed as a webapp. The first step of this process is to create and deploy your portal as a webapp, as described in the section Using e-Commerce Functionality Within a Portal.

Once you have deployed your portal as a webapp, follow these steps:

1. Start your server and log on to the administration client.

2. Navigate to the Property Set Manager. Click on your property set to edit it.

3. You need to use a special destination determiner. Edit your destinationdeterminer property, and set it to be:
   com.beasys.commerce.Webflow.WLCSPortalDestinationDeterminer.

4. In a text editor, open or create your Webflow.properties located in your %WL_COMMERCE_HOME% folder.

   In this folder, you need to create transitions from your portlet to input processors and pipeline processors. It is important to understand that the WLCSDestinationDeterminer will route the flow from your portlet to the input processors and pipeline processors. Once Webflow has traversed through the IPs and PPs, it will forward the request to the URL that you specify in the Webflow method call in your portlet JSP (this will be discussed later). An example Webflow property file is as follows:

   myportlet.jsp.link(mylink) = myportlet.inputprocessor
   myportlet.inputprocessor.success = myportlet.pipeline
   myportlet.pipeline.success = myportlet2.pipeline

   In this example, once Webflow has traversed through the second pipeline processor, it will allow the default destionation determiner to forward to the URL specified in the request.

   In WebLogic Commerce Server with WebLogic Personalization Server, you may have only one webapp that is Webflow enabled. You must identify the property set to be used by Webflow. Do this by adding the following section to your web.xml file located in your web-inf folder:

   <context-param>
      <param-name>WLCS_APPLICATION_URL</param-name> 
      <param-value>/application/commercewf</param-value> 
   </context-param>

   Replace commercewf with the name of your property set.

   Finally, you need to connect to Webflow from your portlet. In your portlet JSP, you must make a call to createWebflowURL. In this call, you must specify two parameters. Specify a parameter called portalized as true, and a parameter called dest with the URL that Webflow should go to after it has finished. For example:

   myportlet.jsp

   <%@ page import="com.beasys.commerce.webflow.*" %>
   <%@ page extends="com.beasys.commerce.portal.admin.PortalJspBase"%>

   <form method="POST"
           action="<%= WebflowJSPHelper.createWebflowURL(
   				           pageContext, 
              "portlet.jsp",
              "link(mylink)",
   	           "&portalized=true&dest=/portal.jsp",
              true) %>">
   ...
   </form>

   In this example, when the user clicks the Submit button the request will be forwarded to the destination of the myportlet.jsp.link(mylink) transition. Once Webflow has finished with all input processors and pipeline processors it has found there, it will forward to portal.jsp. Your dest parameter should refer to your portal page and not your portlet.

5. Test your portal.

If you successfully completed all the steps in this exercise, you should now have Webflow working within your portal.

 

---

Reusing Pieces of the Demo Catalog Application in a Portal

If you start your commerce server and use a browser to navigate to http://localhost:7501/application/wlcs, you can experiment with the WebLogic Commerce Server with WebLogic Personalization Server sample catalog application. There are some useful pieces of functionality in this sample application that you may want to build into your portal site as a portlet. This section explains how to do this.

First, note that the WebLogic Commerce Server with WebLogic Personalization Server catalog application relies on Webflow. Therefore, you must integrate Webflow with your portal. See Using Webflow Within a Portal. Also, the Catalog application uses Commerce features, so you must prepare your portal as described in the section Using e-Commerce Functionality Within a Portal.

After you have followed those directions, complete the following steps.

1. Identify the JSP file in the catalog project that provides the functionality you wish to have in your application. There is no better way to do this than to open JSP files in the %WL_COMMERCE_HOME%/server/webapps/wlcs folder and track the code down. Copy this file into your application folder.

2. Remove from this file any functionality you do not want in your portlet. This includes both links to the WebLogic Commerce Server with WebLogic Personalization Server catalog site and also page-scoped items such as the WebLogic Commerce Server with WebLogic Personalization Server catalog header and footers.

   Make your portlet extend PortalJspBase by adding the following line to the top of the JSP file:

   <%@ page extends="com.beasys.commerce.portal.admin.PortalJspBase"%>

3. Identify the transitions in the default webflow.properties file that correspond to your portlet JSP. Update as necessary.

4. Update the Webflow calls in your JSP (as explained in the previous section).

5. Register your portlet JSP with the server through the administration tool.

6. Add your new portlet to your portal.

7. Test your new portlet.