Implementing User Profiles

In WebLogic Portal, users are represented by user profiles. User profiles provide flexibility in representing, storing, and accessing user attributes. In addition to supporting basic user profiles, WebLogic Portal provides a Unified User Profile (UUP) that can be used to create a virtual enterprise profile.

This section includes information on the following subjects:

• Creating a Unified User Profile

• Creating a Property Set Definition

• Enabling Visitor Self-Registration

 

---

Creating a Unified User Profile

A Unified User Profile provides the capability to leverage user data from external sources such as LDAP servers, legacy systems and databases. This allows for the use of a single profile to access user data from many different sources.

To create a UUP to retrieve user data from external sources, complete the following tasks:

1. Create an EntityPropertyManager EJB to Represent External Data

2. Deploy a ProfileManager That Can Use the New EntityPropertyManager

Create an EntityPropertyManager EJB to Represent External Data

To incorporate data from an external source, you must first create a stateless session bean that implements the methods of the com.bea.p13n.property. EntityPropertyManager remote interface. EntityPropertyManager is the remote interface for a session bean that handles the persistence of property data and the creation and deletion of profile records.

In addition, the stateless session bean should include a home interface and an implementation class. For example:

MyEntityPropertyManager
extends com.bea.p13n.property.EntityPropertyManager

MyEntityPropertyManagerHome
extends javax.ejb.EJBHome

Your implementation class can extend the EntityPropertyManagerImpl class. However the only requirement is that your implementation class is a valid implementation of the MyEntityPropertyManager remote interface. For example:

MyEntityPropertyManagerImpl extends
com.bea.p13n.property.internal.EntityPropertyManagerImpl

or

MyEntityPropertyManagerImpl extends
javax.ejb.SessionBean

Recommended EJB Guidelines

We recommend the following guidelines for your new EJB:

• Your custom EntityPropertyManager is not a default EntityPropertyManager. A default EntityPropertyManager is used to get/set/remove properties in the Portal schema. Your custom EntityPropertyManager does not have to support the following methods. It can throw java.lang.UsupportedOperationException instead:

  getDynamicProperties

  getEntityNames

  getHomeName

  getPropertyLocator

  getUniqueId

• If you want to be able to use the Portal framework and tools to create and remove users in your external data store then you must support the createUniqueId() and removeEntity() methods. However, your custom EntityPropertyManager is not the default EntityPropertyManager so your createUniqueId() method does not have to return a unique number. It must create the user entity in your external data store and then it can return any number, such as -1.

• The following recommendations apply to the EntityPropertyManager() methods that you must support:

  • getProperty() - Use caching. You should support the getProperties method to retrieve all properties for a user at once, caching them at the same time. Your getProperty method should use getProperties.

  • setProperty() - Use caching.

  • removeProperties(), removeProperty() - After these methods are called, a call to getProperty should return null for the property. Remove properties from the cache too.

• Your implementations of the getProperty(), setProperty(), removeProperty(), and removeProperties() methods must include any logic necessary to connect to the external system.

• If you want to cache property data, the methods must be able to cache profile data appropriately for that system. (See the com.bea.p13n.cache package at ../javadoc/index.html.)

• If the external system contains read-only data, any methods that modify profile data must throw a java.lang.UnsupportedOperationException. Additionally, if the external data source contains users that are created and deleted by something other than your WebLogic Portal createUniqueId and removeEntity methods can simply throw an UnsupportedOperationException.

• To avoid class loader dependency issues, make sure that your EJB resides in its own package.

• For ease of maintenance, place the compiled classes of your custom EntityPropertyManager bean in your own JAR file (instead of modifying an existing WebLogic Portal JAR file).

Before you deploy your JAR file, follow the steps in the next section.

Deploy a ProfileManager That Can Use the New EntityPropertyManager

A "user type" is a mapping of a ProfileType name to a particular ProfileManager. This mapping is done in the UserManager EJB deployment descriptor.

To access the data in your new EntityPropertyManager EJB, you must do one of the following:

• In most cases you will be able to use the default deployment of ProfileManager, the UserProfileManager. You will modify the UserProfileManager's deployment descriptor to map a property set and/or properties to your custom EntityPropertyManager. If you support the createUniqueId() and removeEntity() methods in your custom EntityPropertyManager, you can use WebLogic Portal Administration Tools to create a user of type "User" with a profile that can get/set properties using your custom EntityPropertyManager. For more information, refer to Modifying the Existing ProfileManager Deployment Configuration.

• In some cases you may want to deploy a newly configured ProfileManager that will be used instead of the UserProfileManager. This new ProfileManager is mapped to a ProfileType in the deployment descriptor for the UserManager. If you support the createUniqueId() and removeEntity() methods in your custom EntityPropertyManager, you can use the WebLogic Portal Administration Tools (or API) to create a user of type "MyUser" (or anything else you name it) that can get/set properties using the customized deployment of the ProfileManager that is, in turn, configured to use your custom EntityPropertyManager. For more information, refer to Configuring and Deploying a New ProfileManager.

ProfileManager is a stateless session bean that manages access to the profile values that the EntityPropertyManager EJB retrieves. It relies on a set of mapping statements in its deployment descriptor to find data. For example, the ProfileManager receives a request for the value of the DateOfBirth property, which is located in the PersonalData property set. ProfileManager uses the mapping statements in its deployment descriptor to determine which EntityPropertyManager EJB contains the data.

Modifying the Existing ProfileManager Deployment Configuration

If you use the existing UserProfileManager deployment to manage your user profiles, perform the following steps to modify the deployment configuration.

Under most circumstances, this is the method you should use to deploy your UUP. An example of this method is the deployment of the custom EntityPropertyManager for LDAP property retrieval, the LdapPropertyManager. The classes for the LdapPropertyManager are packaged in ldapprofile.jar. The deployment descriptor for the UserProfileManager EJB is configured to map the "ldap" property set to the LdapPropertyManager. The UserProfileManager is deployed in usermgmt.jar.

1. Back up the usermgmt.jar file in your enterprise application root directory.

2. From usermgmt.jar, extract META-INF/ejb-jar.xml and open it for editing.

3. In ejb-jar.xml, find the <env-entry> element, as shown in Listing  6-1:

Listing 6-1 <env-entry> Element

<!-- map all properties in property set ldap to ldap server -->

<env-entry>
 <env-entry-name>PropertyMapping/ldap</env-entry-name>
  <env-entry-type>java.lang.String</env-entry-type>
  <env-entry-value>LdapPropertyManager</env-entry-value>
</env-entry>

and add an <env-entry> element after this to map a property set to your custom EntityPropertyManager, a shown in Listing  6-2:

Listing 6-2 Adding Another <env-entry> Element to Map a Property

<!-- map all properties in UUPExample property set to MyEntityPropertyManager -->

<env-entry>
  <env-entry-name>PropertyMapping/UUPExample</env-entry-name>
  <env-entry-type>java.lang.String</env-entry-type>
  <env-entry-value>MyEntityPropertyManager</env-entry-value>
</env-entry>

4. In ejb-jar.xml, find the <ejb-ref> element shown in Listing  6-3

Listing 6-3 <ejb-ref> Element

<!-- an ldap property manager -->
<ejb-ref>
  <ejb-ref-name>ejb/LdapPropertyManager</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <home>com.bea.p13n.property.EntityPropertyManagerHome</home>
  <remote>com.bea.p13n.property.EntityPropertyManager</remote>
</ejb-ref>

and add a <ejb-ref> element after this to map a reference to an EJB that matches the name from the previous step with ejb/ prepended as shown in Listing  6-4:

Listing 6-4 <ejb-ref> Element Mapping a Reference to an EJB

<!-- an example property manager -->
<ejb-ref>
  <ejb-ref-name>ejb/MyEntityPropertyManager</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <home>examples.usermgmt.MyEntityPropertyManagerHome</home>
  <remote>examples.usermgmt.MyEntityPropertyManager</remote>
</ejb-ref>

The home and remote class names match the classes from your EJB JAR file for your custom EntityPropertyManager.

5. If your EntityPropertyManager implementation handles creating and removing profile records, you must also add Creator and Remover entries. For example:

Listing 6-5 <env-entry> Element that Adds Creator and Remover Entries

<env-entry>
  <env-entry-name>Creator/Creator1</env-entry-name>
  <env-entry-type>java.lang.String</env-entry-type>
  <env-entry-value>MyEntityPropertyManager</env-entry-value>
</env-entry>

<env-entry>
  <env-entry-name>Remover/Remover1</env-entry-name>
  <env-entry-type>java.lang.String</env-entry-type>
  <env-entry-value>MyEntityPropertyManager</env-entry-value>
</env-entry>

This instructs the UserProfileManager to call your custom EntityPropertyManager when creating or deleting user profile records. The names "Creator1" and "Remover1" are arbitrary. All Creators and Removers will be iterated through when the UserProfileManager creates or removes a user profile. The value for the Creator and Remover matches the ejb-ref-name for your custom EntityPropertyManager without the ejb/ prefix.

6. From usermgmt.jar, extract META-INF/weblogic-ejb-jar.xml and open it for editing.

7. In weblogic-ejb-jar.xml, find the elements described in Listing  6-6:

Listing 6-6 weblogic-ejb-jar.xml Elements

<weblogic-enterprise-bean>
  <ejb-name>UserProfileManager</ejb-name>
  <reference-descriptor>
    <ejb-reference-description>
      <ejb-ref-name>ejb/EntityPropertyManager</ejb-ref-name>
      <jndi-name>${APPNAME}.BEA_personalization.
      EntityPropertyManager</jndi-name>
    </ejb-reference-description>

and add an ejb-reference-description to map the ejb-ref for your custom EntityPropertyManager to the JNDI name. This JNDI name must match the name you assigned in weblogic-ejb-jar.xml in the JAR file for your customer EntityPropertyManager. It should look like the example in Listing  6-7:

Listing 6-7 Showing the JNDI Name

<weblogic-enterprise-bean>
  <ejb-name>UserProfileManager</ejb-name>
  <reference-descriptor>
    <ejb-reference-description>
      <ejb-ref-name>ejb/EntityPropertyManager</ejb-ref-name>
      <jndi-name>${APPNAME}.BEA_personalization.
      EntityPropertyManager</jndi-name>
    </ejb-reference-description>
    <ejb-reference-description>
      <ejb-ref-name>ejb/MyEntityPropertyManager
      </ejb-ref-name>
      <jndi-name>${APPNAME}.BEA_personalization.
      MyEntityPropertyManager</jndi-name>
    </ejb-reference-description>

Note the ${APPNAME} string substitution variable. The WebLogic EJB container automatically substitutes the enterprise application name to scope the JNDI name to the application.

8. Update usermgmt.jar for your new deployment descriptors. You can use the jar  uf command to update the modified META-INF/ deployment descriptors.

9. Edit META-INF/application.xml for your enterprise application to add an entry for your custom EntityPropertyManager EJB module as shown in Listing  6-8:

Listing 6-8 Adding an Entry for a Custom EntityPropertyManager EJB Module

<module>
  <ejb>UUPExample.jar</ejb>
</module>

10. If you are using an application-wide cache, you can manage it from the Administration Console if you add a <Cache> tag for your cache to the META-INF/application-config.xml deployment descriptor for your enterprise application like this:

Listing 6-9 Adding a <Cache> Tag to META-INF/application-config.xml

<Cache
  Name="UUPExampleCache"
  TimeToLive="60000"
/>

11. Verify the modified usermgmt.jar and your custom EntityPropertyManager EJB JAR archive are in the root directory of your enterprise application and start WebLogic Server.

12. Use the WebLogic Server Administration Console to verify your EJB module is deployed to the enterprise application and then use the console to add your server as a target for the EJB module. You need to select a target to have your domain's config.xml file updated to deploy your EJB module to the server.

13. Use the E-Business Control Center to create a User Profile (property set) that matches the name of the property set that you mapped to your custom EntityPropertyManager in ejb-jar.xml for the UserProfileManager (in usermgmt.jar). You could also map specific property names in a property set to your custom EntityPropertyManager.

    Note: Be sure to synchronize the new data to your server after the property set is created.

Your new Unified User Profile type is ready to use. You can use the WebLogic Portal Administration Tools to create a user of type "User," and it will use your UUP implementation when the "UUPExample" property set is being modified. When you call createUser("bob", "password") or createUser("bob", "password", null) on the UserManager, several things will happen:

• A user named "bob" is created in the security realm.

• A WebLogic Portal Server profile record is created for "bob" in the WebLogic Portal RDBMS repository.

• If you set up the Creator mapping, the UserManager will call the default ProfileManager deployment (UserProfileManager) which will call your custom EntityPropertyManager to create a record for Bob in your data source.

• Retrieving Bob's profile will use the default ProfileManager deployment (UserProfileManager), and when you request a property belonging to the "UUPExample" property set, the request will be routed to your custom EntityPropertyManager implementation.

Configuring and Deploying a New ProfileManager

If you are going to deploy a newly configured ProfileManager instead of using the default ProfileManager (UserProfileManager) to manage your user profiles, perform the following steps to modify the deployment configuration. In most cases, you will not have to use this method of deployment. Use this method only if you need to support multiple types of users that require different ProfileManager deployments—deployments that allow a property set to be mapped to different custom EntityPropertyManagers based on ProfileType.

An example of this method is the deployment of the custom CustomerProfileManager in customer.jar. The CustomerProfileManager is configured to use the custom EntityPropertyManager (CustomerPropertyManager) for properties in the "CustomerProperties" property set. The UserManager EJB in usermgmt.jar is configured to map the "WLCS_Customer" ProfileType to the custom deployment of the ProfileManager, CustomerProfileManager.

To configure and deploy a new ProfileManager, use this procedure.

1. Back up the usermgmt.jar file in your enterprise application root directory.

2. From usermgmt.jar, extract META-INF/ejb-jar.xml, and open it for editing.

3. In ejb-jar.xml, copy the entire <session> tag for the UserProfileManager, and configure it to use your custom implementation class for your new deployment of ProfileManager.

   In addition, you could extend the UserProfileManager home and remote interfaces with your own interfaces if you want to repackage them to correspond to your packaging (for example., examples.usermgmt.MyProfileManagerHome, examples.usermgmt.MyProfileManager).

   However, it is sufficient to replace the bean implementation class:

   You must create an <env-entry> element to map a property set to your custom EntityPropertyManager. You must also create a <ejb-ref> element to map a reference to an EJB that matches the name from the PropertyMapping with ejb/ prepended. The home and remote class names for your custom EntityPropertyManager match the classes from your EJB JAR file for your custom EntityPropertyManager.

   Also, if your EntityPropertyManager implementation handles creating and removing profile records, you must also add Creator and Remover entries. This instructs your new ProfileManager to call your custom EntityPropertyManager when creating or deleting user profile records.

   Note: The name suffixes for the Creator and Remover, "Creator1" and "Remover1", are arbitrary. All Creators and Removers will be iterated through when your ProfileManager creates or removes a user profile. The value for the Creator and Remover matches the <ejb-ref-name> for your custom EntityPropertyManager without the ejb/ prefix.

4. In ejb-jar.xml, you must add an <ejb-ref> to the UserManager EJB section to map your ProfileType to your new deployment of the ProfileManager, as shown in Listing  6-10:

Listing 6-10 Adding an <ejb-ref> to the UserManager EJB Section

<ejb-ref>
  <ejb-ref-name>ejb/ProfileType/UUPExampleUser</ejb-ref-name>
  <ejb-ref-type>Session</ejb-ref-type>
  <home>com.bea.p13n.usermgmt.profile.ProfileManagerHome</home>
  <remote>com.bea.p13n.usermgmt.profile.ProfileManager</remote>
</ejb-ref>

The <ejb-ref-name> must start with ejb/ProfileType/ and must end with the name that you want to use as the profile type as an argument in the createUser() method of UserManager.

5. From usermgmt.jar, extract META-INF/weblogic-ejb-jar.xml and open it for editing.

6. In weblogic-ejb-jar.xml, copy the weblogic-enterprise-bean tag, shown in Listing  6-11, for the UserProfileManager and configure it for your new ProfileManager deployment:

Listing 6-11 <weblogic-enterprise-bean> Tag for the UserProfileManager

<weblogic-enterprise-bean>
  <ejb-name>MyProfileManager</ejb-name>
  <reference-descriptor>
    <ejb-reference-description>
      <ejb-ref-name>ejb/EntityPropertyManager</ejb-ref-name>
        <jndi-name>${APPNAME}.BEA_personalization.
        EntityPropertyManager</jndi-name>
      </ejb-reference-description>
      <ejb-reference-description>
        <ejb-ref-name>ejb/PropertySetManager</ejb-ref-name>
        <jndi-name>${APPNAME}.BEA_personalization.
        PropertySetManager</jndi-name>
      </ejb-reference-description>
      <ejb-reference-description>
        <ejb-ref-name>ejb/MyEntityPropertyManager
        </ejb-ref-name>
        <jndi-name>${APPNAME}.BEA_personalization.
        MyEnitityPropertyManager</jndi-name>
      </ejb-reference-description>
  </reference-descriptor>
  <jndi-name>${APPNAME}.BEA_personalization.
  MyProfileManager</jndi-name>
</weblogic-enterprise-bean>

You must create an <ejb-reference-description> to map the <ejb-ref> for your custom EntityPropertyManager to the JNDI name. This JNDI name must match the name you assigned in weblogic-ejb-jar.xml in the JAR file for your custom EntityPropertyManager.

Note the ${APPNAME} string substitution variable. The WebLogic Server EJB container automatically substitutes the enterprise application name to scope the JNDI name to the application.

7. In weblogic-ejb-jar.xml, copy the <transaction-isolation> tag for the UserProfileManager, shown in Listing  6-12, and configure it for your new ProfileManager deployment:

Listing 6-12 <transaction-isolation> Tag for the UserProfileManager

<transaction-isolation>
  <isolation-level>TRANSACTION_READ_COMMITTED
  </isolation-level>
  <method>
    <ejb-name>MyProfileManager</ejb-name>
    <method-name>*</method-name>
  </method>
</transaction-isolation>

8. Create a temporary usermgmt.jar for your new deployment descriptors and your new ProfileManager bean implementation class. This temporary EJB JAR archive should not have any container classes in it. Run ejbc to generate new container classes.

9. Edit META-INF/application.xml for your enterprise application to add an entry for your custom EntityPropertyManager EJB module, as shown in Listing  6-13:

Listing 6-13 Adding an Entry to a Custom EntityPropertyManager EJB Module

<module>
  <ejb>UUPExample.jar</ejb>
</module>

10. If you are using an application-wide cache, you can manage it from the WebLogic Server Administration Console if you add a <Cache> tag for your cache to the META-INF/application-config.xml deployment descriptor for your enterprise application as shown in Listing  6-14:

Listing 6-14 Adding a <Cache> Tag to a META-INF/application-config.xml

<Cache
  Name="UUPExampleCache" TimeToLive="60000"
/>

11. Verify the modified usermgmt.jar and your custom EntityPropertyManager EJB JAR archive are in the root directory of your enterprise application and start your server.

12. Use the WebLogic Server Administration Console to verify your EJB module is deployed to the enterprise application, then use the WebLogic Server Administration Console to add your server as a target for the EJB module. You must select a target to have your domain's config.xml file updated to deploy your EJB module to the server.

13. Use the E-Business Control Center to create a User Profile (property set) that matches the name of the property set that you mapped to your custom EntityPropertyManager in ejb-jar.xml for the UserProfileManager (in usermgmt.jar). You could also map specific property names in a property set to your custom EntityPropertyManager.

    Note: Be sure to synchronize the new data to your server after the property set is created.

14. Your new Unified User Profile type is ready to use. You can use the WebLogic Portal Administration Tools to create a user of type "UUPExampleUser," and it will use your UUP implementation when the "UUPExample" property set is being modified. That is because you mapped the ProfileType using an <ejb-ref> in your UserManager deployment descriptor, ejb/ProfileType/UUPExampleUser.

    Note: Tell your administrators that when they create a user in the WebLogic Portal Administration Tools, they must select the new user type.

    Now, when you call createUser("bob", "password", "UUPExampleUser") on the UserManager, several things will happen:

    • A user named "bob" is created in the security realm.

    • A WebLogic Portal Server profile record is created for "bob" in the WebLogic Portal RDBMS repository.

    • If you set up the Creator mapping, the UserManager will call your new ProfileManager deployment, which will call your custom EntityPropertyManager to create a record for Bob in your data source.

    • Retrieving Bob's profile will use your new ProfileManager deployment, and when you request a property belonging to the "UUPExample" property set, the request will be routed to your custom EntityPropertyManager implementation.

Retrieving User Profile Data from LDAP

The LdapRealm security realm and the LdapPropertyManager unified user profile (UUP) for retrieving user properties from LDAP are independent of each other. They do not share configuration information and there is no requirement to use either one in conjunction with the other. A security realm has nothing to do with a user profile. A security realm provides user/password data, user/group associations, and group/group associations. A user profile provides user and group properties. A password is not a property.

In order to successfully retrieve the user profile from the LDAP server, ensure that you've done the following:

1. If you have already deployed the application on a WebLogic Portal instance, stop the server.

2. Deploy the ldapprofile.jar component within your application.

   The LdapPropertyManager EJB in ldapprofile.jar has been enhanced as of 7.0 SP2 to allow for the inspection of the LDAP schema to determine multi-valued versus single-value LDAP attributes, to allow for multiple userDN/groupDN, and to allow for SUBTREE_SCOPE searches for users and groups in the LDAP server. Following are more detailed explanations:

   Before this enhancement, an attribute that is defined as multi-valued in the LDAP server's schema, but had only one value, was stored in memory as a single value property by the LdapPropertyManager. This could cause problems in the rules engine when this situation was encountered:

   • A multi-valued LDAP property had a single value.

   • A rule was created in Portal that used the property as a multi-valued property.

   • The rules engine expects the property to be a java.util.Collection because it is multi-valued, but it was not, because the LdapPropertyManager saw it as single valued and stored it that way.

   This change allows a developer to configure the ejb-jar.xml deployment descriptor for the LdapPropertyManager EJB to specify that the LDAP schema be used to determine if a property is single value or multi-value.

   This is done by editing ejb-jar.xml to setting the following env-entries:

   <!-- Flag to specify if LDAP attributes will be determined to be single value or multi-value via the schema obtained from the attribute.  If false, then the attribute is stored as multi-valued (a Collection) only if it has more than one value.  Leave false unless you intend to use multi-valued LDAP attributes that may have only one value.  Using true adds overhead to check the LDAP schema.  Also, if you use true beware that most LDAP attributes are multi-value.  For example, iPlanet Directory Server 5.x uses multi-value for givenName, which you may not expect unless you are familiar with LDAP schemas.  -->

   <env-entry>
       <env-entry-name>config/detectSingleValueFromSchema
       </env-entry-name>
       <env-entry-type>java.lang.Boolean</env-entry-type>
       <env-entry-value>true</env-entry-value>
   </env-entry>

   <!-- Value of the name of the attribute in the LDAP schema that is used to determine single value or multi-value (RFC2252 uses SINGLE-VALUE) This attribute in the schema should be true for single value and false or absent from the schema otherwise. The value only matters if config/detectSingleValueFromSchema is true. --> 

   <env-entry>
       <env-entry-name>config/singleValueSchemaAttribute
       </env-entry-name>
       <env-entry-type>java.lang.String</env-entry-type>
       <env-entry-value>SINGLE-VALUE</env-entry-value>
   </env-entry>

   It is not recommended that true be used for config/detectSingleValueFromSchema unless you are going to write rules that use multi-valued LDAP attributes that have a single value. Using config/detectSingleValueFromSchema = true adds the overhead of checking the LDAP schema for each attribute instead of the default behavior (config/detectSingleValueFromSchema = false), which only stores an attribute as multi-valued (in a Collection) if it has more than one value.

   This patch also implements changes that allow you to use SUBTREE_SCOPE searches for users and groups. It also allows multiple base userDN and groupDN to be specified. The multiple base DN can be used with SUBTREE_SCOPE searches enabled or disabled.

   A SUBTREE_SCOPE search begins at a base userDN (or groupDN) and works down the branches of that base DN until the first user (or group) is found that matches the username (or group name).

   To enable SUBTREE_SCOPE searches you must set the Boolean config/objectPropertySubtreeScope env-entry in the ejb-jar.xml for ldapprofile.jar to true and then you must set the config/userDN and config/groupDN env-entry values to be equal to the base DNs from which you want your SUBTREE_SCOPE searches to begin.

   For example, if you have users in ou=PeopleA,ou=People,dc=mycompany,dc=com and in ou=PeopleB,ou=People,dc=mycompant,dc=com then you could set config/userDN to ou=People,dc=mycompant,dc=com and properties for these users would be retrieved from your LDAP server because the user search would start at the "People" ou and work its way down the branches (ou="PeopleA" and ou="PeopleB").

   You should not create duplicate users in branches below your base userDN (or duplicate groups below your base groupDN) in your LDAP server. For example, your LDAP server will allow you to create a user with the uid="userA" under both your PeopleA and your PeopleB branches. The LdapPropertyManager in ldapprofile.jar will return property values for the first userA that it finds.

   It is recommended that you do not enable this change (by setting config/objectPropertySubtreeScope to true) unless you need the flexibility offered by SUBTREE_SCOPE searches.

   An alternative to SUBTREE_SCOPE searches (with or without multiple base DNs) would be to configure multiple base DNs and leave config/objectPropertySubtreeScope set to false. Each base DN would have to be the DN that contains the users (or groups) because searches would not go any lower than the base DN branches. The search would cycle from one base DN to the next until the first matching user (or group) is found.

   The new ejb-jar.xml deployment descriptor is fully commented to explain how to set multiple DNs, multiple usernameAttributes (or groupnameAttributes), and how to set the objectPropertySubtreeScope flag.

3. Start the server and deploy the application.

4. Start the WebLogic Server Administration Console for the active domain.

 

---

Creating a Property Set Definition

Property sets are the schemas for personalization attributes. They are a convenient way to give a name to a group of properties for a specific purpose. For example, in the sampleportal-project, the User Profile "Avitek" has a property set that defines properties for an e-commerce customer, such as First Name, Last Name, Home Phone, E-mail, and Customer Type. Use the E-Business Control Center to create property sets and define the properties that make up these property sets.

This section describes how to register a customer user profile:

Registering Custom User Profiles

The property set editor works the same way for all property sets. In this exercise, the E-Business Control Center will be used to create and modify User Profile properties. These examples can be used to register a custom user profile. You can follow the same procedures to create and modify property sets for Events, HTTP Requests, HTTP Sessions, and the Catalog Structure.

You can set a default profile type for each web application by setting a context parameter in web.xml for DEFAULT_USER_PROFILE_TYPE. For example:

<context-param>
<param-name>DEFAULT_USER_PROFILE_TYPE</param-name>
<param-value>WLCS_Customer</param-value>
</context-param>

To register a custom user profile, complete the following steps:

1. Start the E-Business Control Center and ensure that it is connected to a server. For information on starting the E-Business Control Center and connecting it to a server, refer to "System Administration" in the Administration Guide at http://download.oracle.com/docs/cd/E13218_01/wlp/docs70/admin/sysadmin.htm.

   The Explorer window opens as shown in Figure  6-1.

   Figure 6-1 E-Business Control Center Window

   
    

2. Open the appropriate project file. For the example in this procedure, you would open samples —> portal —> samplePortalDomain —> beaApps —> sampleportal-project.

3. Open the Event Editor as follows:

   1. In the Explorer window, select the User Profiles icon. A list of User Profiles appears in the User Profiles field, as shown in Figure  6-2

      Figure 6-2 E-Business Control Center Explorer with User Profiles Icon Selected

      
       

   2. Click the New icon to open the New menu and then select User Profile, as shown in Listing  6-3.

      Figure 6-3 New Menu (Opened by Clicking New Icon)

      
       

      The User Profile Editor window appears, as shown in Figure  6-4.

      Figure 6-4 User profile Editor Window

      
       

4. Click New.

   The Edit Property window appears (Figure  6-5).

   Figure 6-5 Event Property Window

   
    

5. In the Edit Property window, complete these steps:

   1. In the Name field, enter a unique name for the property no longer than 100 characters (required).

      Warning: Do not enter LDAP in the Name field.

   2. In the Description field, enter a description of the property no longer than 254 characters (optional).

   3. In the Data type list, select the data type. If you select Boolean as the data type, for example, the Selection mode and Value range are no longer available. The default for Boolean is Single, Restricted.

   4. In the Selection mode list, select either Single or Multiple. The value you select here determines the number of property values you can set: one (Single) or multiple (Multiple).

   5. In the Value range list, select whether the value is Restricted or Unrestricted.

   6. Click Add Values.

      One of two types of Enter Property Values windows appears. The type of Enter Property Values window that appears depends on the values selected. This is because, depending on the data type, different steps are required for entering values and setting default values. The following property categories are available:

   • Properties with Boolean or a Single Value and Single Default.

   • Properties with Multiple Values and Single, Multiple, or All Defaults

   • Properties with Date and Time Values

Properties with Boolean or a Single Value and Single Default

To enter the default value for Boolean property or a property with a single value and a single default (unrestricted), complete the following steps:

1. In the applicable Enter Property Value window (Figure  6-6 or Figure  6-7), perform one of the following:

   • For a Boolean property, select either True or False.

   • For a Single Value, Single Default property, enter a value and click Add.

     Figure 6-6 Enter Property Values Window—Boolean Values Required

     
      

     Figure 6-7 Enter Property Values Window—Single Value, Single Default Required

     
      

2. Click OK.

   The Edit Property Value window closes, revealing the Edit Property window with the selected value(s) appearing in the Value list; for example as shown in Listing  6-8.

   Figure 6-8 Edit Property Window with Text Value

   
    

3. Click OK.

Properties with Multiple Values and Single, Multiple, or All Defaults

To enter multiple property values and set one or more defaults (unrestricted), complete the following steps:

1. In the applicable Enter Property Values window, enter a value, and then click Add.

   The new values will appear in the Values list box, as shown in Figure  6-9, Figure  6-10, and Figure  6-11.

   Figure 6-9 Enter Property Values—Multiple Values, Single Default

   
    

   Figure 6-10 Enter Property Values—Multiple Values, Multiple Restricted Defaults

   
    

   Figure 6-11 Enter Property Values—Multiple Values, Multiple Unrestricted Defaults

   
    

2. Repeat step 1. until you have entered all necessary values.

3. To select one or more default values, complete one of the following:

   • If you do not want to select a default, go to step 5.

   • For multiple values with a single default, select the value (radio button) that you want to set as the default, and then click OK.

   Note: To remove the default value for a property with multiple values and a single default, click Deselect All.

   • For multiple values with multiple restricted defaults, select the value (check boxes) that you want to set as defaults, and then click OK.

   Note: For multiple values without restrictions (that is, the Value range is Unrestricted), you do not need to select any defaults.

4. In the Edit Property window, click OK.

Properties with Date and Time Values

Properties with date and time values can use all Selection mode and Value range settings.

To enter date and time values and set one or more defaults, complete the following steps:

1. In the Edit Properties window, select Date/Time from the Data type drop-down list (shown in Figure  6-12) and select Add Values.

   Figure 6-12 Date type Menu with Date/Time Selected

   
    

   The Enter Property Value window for date and time values appears (Figure  6-13).

   Figure 6-13 Date/Time Enter Property Value Window

   
    

2. Click the drop-down arrow in the Date list.

   A calendar appears, as shown in Figure  6-14.

   Figure 6-14 Enter Property Value Window with Calendar Displayed

   
    

3. Select a date from the calendar; for example June 14.

   The calendar disappears and the selected date appears in the date edit box, as shown in Figure  6-15

   Figure 6-15 Selected Date Appears in Date Edit Box

   
    

4. In the Time field, enter a time.

5. Click Add.

   The new time and date appear in the Values list, as shown in Figure  6-16.

   Figure 6-16 Date and Time Appear in Values List

   
    

6. To add more dates and times, repeat step 1. through step 5. until you have entered all the necessary values.

7. To select one or more default values, complete one of the following:

   • If the event has a single date and time with a single default (restricted), click OK.

   • If the event has multiple dates and times with a single default (restricted), select the value (radio button) that you want to set as the default, and then click OK.

   • If the event has multiple dates and times with multiple defaults (unrestricted), select the values (check boxes) that you want to set as the default, and then click OK.

8. In the Edit Event Property window, click OK.

Updating a Registered Custom Event

Whenever you make changes to a custom event's code, you should update that event's registration. Updating the registration lets the E-Business Control Center know about the changes in the custom event and aids campaign developers using the E-Business Control Center to modify any scenario actions that refer to the event.

To update a custom event, complete the following steps.

1. Start the E-Business Control Center and ensure that it is connected to WebLogic Server.

   The Explorer window opens.

2. Ensure that the correct project file is open and select the Site Infrastructure tab.

3. In the Explorer window, select the Events icon. A list of Events appears in the Events field as shown in Figure  6-17.

   Note: You cannot edit standard Events.

   Figure 6-17 Explorer Window

   
    

4. Double-click the custom event that you want to edit. The Event Editor window opens as shown in Figure  6-18. The Event properties field displays a list of existing properties.

   Figure 6-18 Event Editor Window

   
    

5. In the Event properties field, double-clcik the property that you want to edit.

   The Edit Property window opens as shown in Figure  6-19.

   Figure 6-19 Edit Property Window

   
    

6. To change the Data type, Selection mode, or Value range, select a setting from the appropriate list box.

   Note: If you change the property setting Data type, Selection mode, or Value range, the associated values will be erased.

7. To add or change values, click Edit Values. The Enter Property Value window opens as shown in Figure  6-20.

   Figure 6-20 Enter Property Value Window

   
    

   1. To remove a value, select the value, and then click Remove.

   2. To add a value, enter the value, and then click Add.

   3. To change a value, select the value, remove it, and then add the new value.

   4. If required, select the default value or values.

   5. To remove the default value for a property with multiple values and a single default, click Deselect All.

   6. Click OK. The Enter Property Value window closes.

8. After you have finished updating the properties or values for the event, click OK in the Edit Event Property window.

 

---

Enabling Visitor Self-Registration

Visitors to Websites often need to register before they can proceed with using the site's features; for example, an online bookstore might require a visitor to register with them before they can actually buy books or other merchandise. Registration is valuable because it makes using a Website more convenient for the visitor because it stores pertinent information about them—called a customer profile—that is ncessary for each transaction, relieving the visitor of the need to re-enter this information whenever a transaction is made. It is convenient for your enterprise because it stores visitor data, which allows you to maintain information about people likely to use your service.

WebLogic Portal provides a set of JSP Webflow templates that create a customer profile as the visitor self-registers. You can use these components as is or tailor them for your specific needs. This section describes those JSPs and Webflow components and dicusses how they are used.

Implementing Customer Profile JSPs

WebLogic Portal provides a Login and Registration service comprised of five JSP templates you can use to enable visitor self-registration. You can use these templates as they are or you can modify them to meet your specific needs. This section describes those templates and shows you how to implement them.

This section discusses the following templates:

• login.jsp

• badlogin.jsp

• newuser.jsp

• newuserforward.jsp

• usercreationforward.jsp

login.jsp

The login.jsp template provides customers who have not yet registered with your site an entry point into a page that allows them to register (create their initial customer profile) for subsequent use on the site. Since this page is the entry point to the checkout process, it also establishes mechanisms (such as sessions) that will allow customers to continue their shopping experience.

Description

Figure  6-21 shows an example of a Web page formatted with the login.jsp template.

Figure 6-21 login.jsp Formatted Web Page

 

How login.jsp Works

If an unregistered customer clicks Create in the portlet, the next page loaded allows the customer to create a profile and a username/password combination (newuser.jsp). After the customer has registered, the customer is automatically logged in and forwarded to the newusercreation.jsp template, which allows customers to continue shopping, view their shopping carts, or check out. If the auto-login is unsuccessful, the login.jsp template is loaded for the customer to enter their username and password. If the customer's login attempt is unsuccessful, the badlogin.jsp is loaded.

Notes: The option to proceed to checkout is only provided on the newusercreation.jsp template if there are items in the customer's shopping cart.

Events

The login.jsp template presents a customer with two buttons, only one of which is considered an event. The event triggers a particular response in the default Webflow that allows customers to continue. The other button is a standard HTML Submit button that posts the page back to the WebLogic Server for authentication. Table  6-1 provides information about the event and the business logic it invokes.

Table 6-1 login.jsp Events

Event	Webflow Response(s)
button.createUser	No business logic required. Loads newuser.jsp.

 

The Login button is not an event that would trigger a Webflow response. Rather, when a customer clicks the button, control is turned over to the WebLogic Server (specifically, the RDBMS realm of the WebLogic Portal). The WebLogic Server remembers the HTTP request, determines whether the customer's username and password combination is correct, and then reinvokes the Webflow using the request.

badlogin.jsp

The badlogin.jsp template (shown in Figure  6-22) informs a customer that they have entered an invalid username/password combination, and allows the customer to try logging into a site again by providing a valid username/password combination. Except for the error message, it behaves exactly as the login.jsp template previously described.

Figure 6-22 badlogin.jsp Formatted Web Page

 

newuser.jsp

The newuser.jsp template allows a new customer to register with your e-commerce site by creating their customer profile, which includes personal information, shipping address information, payment information (optional), and account information.

Description

xxx through xxx show an example of how a Web page formatted with newuser.jsp might appear in a browser.

Figure 6-23 Web Page Formatted with newuser.jsp — Personal Information

 

How newuser.jsp Works

The page prior to newuser.jsp is the customer login page (login.jsp). If no errors are found after a customer enters their initial profile information, customers are auto-logged in and forwarded to a welcome page where they can select from the various links to continue shopping or check out (newusercreation.jsp). If errors are found, the newuser.jsp is reloaded with an appropriate message next to the invalid form fields.

This template is part of the sampleapp_user namespace in the Webflow.

JSP Templates Included by newuser.jsp

newuser.jsp includes three additional JSP templates when it is implemented. These JSPs provides a standardized format for both the form presentation and error handling in all JSP templates that prompt customers for shipping address, credit card information, and demographic information. These templates are described in the following paragraphs.

newaddresstemplate.inc This template provides a standardized format for both the form field presentation and error handling included in all JSP templates that prompt customers for a shipping address, except addaddress.jsp. The form fields are organized in a table, and upon form submission, the input processors associated with the newaddresstemplate.inc template will validate the form to ensure that all required fields contain values. If errors are detected, the newaddresstemplate.inc template will be redisplayed, with an error message at the top and the invalid field labels shown in a red (as opposed to the original black) font. Previously entered correct information will still be displayed in the form.

The behavior described above is invoked on the newaddresstemplate.inc template by using the getValidatedValue JSP tag, as shown in Listing  6-15.

Listing 6-15 Use of the getValidatedValue JSP Tag on newaddresstemplate.inc

<!-- begin table with customer's shipping address information -->

<table width="90%" border="0">
   <tr>
      <td width="26%"><webflow:getValidatedValue
         fieldName="<%=HttpRequestConstants.CUSTOMER_SHIPPING_ADDRESS1%>"
         fieldValue="customerShippingAddress1" fieldStatus="status"
         validColor="black" invalidColor="red" unspecifiedColor="black"
         fieldColor="fontColor" />
         <div class="tabletext"><font color=<%= fontColor %>><b>Address </b>
            </font>
         </div>
      </td>
      <td width="74%"> <input type="text"
         name="<%=HttpRequestConstants.CUSTOMER_SHIPPING_ADDRESS1%>"
         value="<%=customerShippingAddress1%>" size="30" maxlength="30">*
      </td>
   </tr>
   .
   .
   .
</table>

newcctemplate.inc This template provides a standardized format for both the form presentation and error handling in all JSP templates that prompt customers for credit card/payment information. The form fields are organized in a table, and upon form submission, the input processors associated with the newcctemplate.inc template will validate the form to ensure that all required fields contain values. If errors are detected, the newcctemplate.inc template will be redisplayed, with an error message at the top and the invalid field labels shown in a red (as opposed to the original black) font. Previously entered correct information will still be displayed in the form.

The behavior described above is invoked on the newcctemplate.inc template by using the getValidatedValue JSP tag, as shown in Listing  6-16.

Listing 6-16 Use of the getValidatedValue JSP Tag on newcctemplate.inc

<table>
.
.
.
   <td width="27%"><webflow:getValidatedValue
      fieldName="<%=HttpRequestConstants.CUSTOMER_CREDITCARD_HOLDER%>"
      fieldValue="customerCreditCardHolder" fieldStatus="status"
      validColor="black" invalidColor="red"
      unspecifiedColor="black"
      fieldColor="fontColor" />
      <div class="tabletext">
         <font color=<%= fontColor %>><b>Name on card</b>
         </font>
      </div>  
   </td>
   <td width="73%"> <input type="text"
      name="<%=HttpRequestConstants.CUSTOMER_CREDITCARD_HOLDER%>"
      value="<%=customerCreditCardHolder%>" size="30" maxlength="50">*
   </td>
.
.
.
</table>

newdemographictemplate.inc This template provides a standardized format for both the form presentation and error handling in all JSP templates that prompt customers for demographic information. The radio buttons are organized in a table, and upon form submission, the input processors associated with the newdemographictemplate.inc template will validate the form to ensure that all required fields contain values. If errors are detected, the newdemographictemplate.inc template will be redisplayed, with an error message at the top of the including page and the invalid field labels shown in a red (as opposed to the original black) font. Previously entered correct information will still be displayed in the form.

The behavior described above is invoked on the newdemographictemplate.inc template by using the getValidatedValue JSP tag, as shown in Listing  6-17.

Listing 6-17 Use of the getValidatedValue JSP Tag on newdemographictemplate.inc

<webflow:getValidatedValue fieldName="<%=HttpRequestConstants.CUSTOMER_GENDER%>"
   fieldDefaultValue="<%=(String)currentPropertyValue%>"
   fieldValue="genderValue" fieldStatus="status" validColor="black"
   invalidColor="red" unspecifiedColor="black" fieldColor="fontColor" />

   <td width="26%"><div class="tabletext"><b><font color=<%= fontColor %>>
      Gender*</font></b></div>
   </td>
   <td width="74%">

   <%	// get the property values for Gender
   propertyBean.setPropertyName(GENDER);
   				property = propertyBean.getPropertyObject();
				   if(property == null || property.getRestrictedValues() == null)
   arr = new Object[0];
				   else				 arr = property.getRestrictedValues().toArray();%>

				   <ps:getRestrictedPropertyValues propertySetName="Demographics"
      propertySetType="USER" propertyName="<%= GENDER %>" id="arr" 
      result="foobar" />

   <table width="100%" border="0" cellpadding="0"
      cellspacing="0"><es:forEachInArray id="valueObject" array="<%= arr %>"
         type="String">
      <tr>
         <td width="4%"><input type="radio" name="
         <%= HttpRequestConstants.CUSTOMER_GENDER %>" value="<%= valueObject %>"
         <% if ( valueObject.equals(genderValue) ) { %>CHECKED<% } %>></td>
         <td><%= valueObject %></td>
      </tr>
      </es:forEachInArray>
   </table>

Events

The newuser.jsp template presents a customer with two buttons, each of which is considered an event. These events trigger a particular response in the default Webflow that allows customers to continue. While this response can be to load another JSP, it is usually the case that an input processor or pipeline component is invoked first. Table  6-2 describes the business logic these events invoke.

Table 6-2 newuser.jsp Events

Event	Webflow Response(s)
button.cancel	GetCategoryIP GetTopCategories Pipeline
button.save	CustomerProfileIP CustomerProfile Pipeline

 

Table  6-3 briefly describes each of the Pipeline components described Table  6-2.

Table 6-3 newuser.jsp Associated Pipelines

Pipeline	Description
CustomerProfile	Contains EncryptedCreditCardPC and RegisterUserPC, and is transactional.

 

newuser.jsp Form Fields

The primary purpose of the newuser.jsp template is to allow customers to enter their profile information using various HTML form fields. It is also used to pass needed information to the Webflow.

The form fields used in the newuser.jsp template, most of which are imported from other templates, and a description for each of these form fields are listed in Table  6-4.

Note: If a form field is imported from another template, it is indicated in the description. Form fields without import information are in the newuser.jsp template.

Table 6-4 newuser.jsp Form Fields  

Parameter Name	Type	Description
"event"	Hidden	Indicates which event has been triggered. It is used by the Webflow to determine what happens next.
"origin"	Hidden	The name of the current page (newuser.jsp), used by the Webflow.
"namespace"	Hidden	The namespace for the JSP; sampleapp_user in this JSP.
HttpRequestConstants. CUSTOMER_FIRST_NAME	Textbox	The customer's first name.
HttpRequestConstants. CUSTOMER_MIDDLE_NAME	Textbox	The customer's middle initial.
HttpRequestConstants. CUSTOMER_LAST_NAME	Textbox	The customer's last name.
HttpRequestConstants. CUSTOMER_ADDRESS1	Textbox	The first line in the customer's street address.
HttpRequestConstants. CUSTOMER_ADDRESS2	Textbox	The second line in the customer's street address.
HttpRequestConstants. CUSTOMER_CITY	Textbox	The city in the customer's address.
HttpRequestConstants. CUSTOMER_STATE	Listbox	The state in the customer's address. Imported from states.inc.
HttpRequestConstants. CUSTOMER_ZIPCODE	Textbox	The zip code in the customer's address.
HttpRequestConstants. CUSTOMER_COUNTRY	Listbox	The country in the customer's address. Imported from countries.inc.
HttpRequestConstants. CUSTOMER_HOME_PHONE	Textbox	The customer's home phone number.
HttpRequestConstants. CUSTOMER_BUSINESS_PHONE	Textbox	The customer's business phone number.
HttpRequestConstants. CUSTOMER_EMAIL	Textbox	The customer's e-mail address.
HttpRequestConstants. CUSTOMER_EMAIL_OPT_IN	Checkbox	Indicates that the customer wants to receive promotional items via e-mail.
HttpRequestConstants. SAME_AS_ABOVE	Checkbox	Indicates that the customer's shipping address is the same as the contact address. Imported from newaddresstemplate.inc.
HttpRequestConstants. CUSTOMER_SHIPPING_ADDRESS1	Textbox	The first line in the customer's shipping address. Imported from newaddresstemplate.inc.
HttpRequestConstants. CUSTOMER_SHIPPING_ADDRESS2	Textbox	The second line in the customer's shipping address. Imported from newaddresstemplate.inc.
HttpRequestConstants. CUSTOMER_SHIPPING_CITY	Textbox	The city in the customer's shipping address. Imported from newaddresstemplate.inc.
HttpRequestConstants. CUSTOMER_SHIPPING_STATE	Listbox	The state in the customer's shipping address. Imported from newaddresstemplate.inc.
HttpRequestConstants. CUSTOMER_SHIPPING_ZIPCODE	Textbox	The zip/postal code in the customer's shipping address. Imported from newaddresstemplate.inc.
HttpRequestConstants. CUSTOMER_SHIPPING_COUNTRY	Listbox	The country in the customer's shipping address. Imported from newaddresstemplate.inc.
HttpRequestConstants. CUSTOMER_GENDER	Radio buttons	Identifies the customer as male or female. Imported from newdemographictemplate.inc.
HttpRequestConstants. CUSTOMER_DATE_OF_BIRTH	Textboxes	The customer's date of birth. Imported from newdemographictemplate.inc.
HttpRequestConstants. CUSTOMER_OCCUPATION	Radio buttons	The customer's job description. Imported from newdemographictemplate.inc.
HttpRequestConstants. CUSTOMER_EMPLOYMENT_STATUS	Radio buttons	Identifies if the customer has a job at the time of registration. Imported from newdemographictemplate.inc.
HttpRequestConstants. CUSTOMER_MARITAL_STATUS	Radio buttons	Identifies the customer's marital status. Imported from newdemographictemplate.inc.
HttpRequestConstants. CUSTOMER_EDUCATION_LEVEL	Radio buttons	Identifies how much formal education the customer has completed. Imported from newdemographictemplate.inc.
HttpRequestConstants. CUSTOMER_INCOME_RANGE	Radio buttons	Identifies the customer's yearly income. Imported from newdemographictemplate.inc.
HttpRequestConstants. CUSTOMER_QUALITY	Radio buttons	Ranks customer from beginner to expert in using your product. Imported from newdemographictemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_TYPE	Listbox	The type of the customer's credit card. Imported from newcctemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_HOLDER	Textbox	The name on the credit card. Imported from newcctemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_NUMBER	Textbox	The number of the customer's credit card. Imported from newcctemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_MONTH	Listbox	The month of the customer's credit card expiration date. Imported from newcctemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_YEAR	Listbox	The year of the customer's credit card expiration date. Imported from newcctemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_ADDRESS1	Textbox	The first line in the customer's billing address. Imported from newcctemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_ ADDRESS2	Textbox	The second line in the customer's billing address. Imported from newcctemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_CITY	Textbox	The city in the customer's billing address. Imported from newcctemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_STATE	Listbox	The state in the customer's billing address. Imported from newcctemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_ZIPCODE	Textbox	The zip/postal code in the customer's billing address. Imported from newcctemplate.inc.
HttpRequestConstants. CUSTOMER_CREDITCARD_COUNTRY	Listbox	The country in the customer's billing address. Imported from newcctemplate.inc.
HttpRequestConstants.USER_NAME	Textbox	An identity chosen by the customer for login.
HttpRequestConstants.PASSWORD	Password	A password chosen by the customer for login.
HttpRequestConstants. CONFIRM_PASSWORD	Password	Confirmation of the password chosen by the customer for login.

 

Note: Parameters that are literals in the JSP code are shown in quotes, while non-literals will require scriptlet syntax (such as
<%= HttpRequestConstants.USER_NAME %>) for use in the JSP.

newusercreation.jsp

The newusercreation.jsp template informs a customer who has just created a new user profile that they have been logged in and that registration was successful. It also provides the customer with the opportunity to return to their shopping experience through several navigation options.

Description

Figure  6-24 shows an example of a Web page formatted with newusercreation.jsp.

Figure 6-24 Web Page Formatted with newusercreation.jsp

 

The option to proceed to checkout is only provided on the newusercreation.jsp template if there are items in the customer's shopping cart. Otherwise, the newusercreation.jsp template will leave out this option as shown in Figure  6-25.

Figure 6-25 Web Page Formatted with newusercreation.jsp When Shopping Cart is Empty

 

How newusercreation.jsp Works

Customers arrive at the newusercreation.jsp template when they have successfully created a new user profile and the auto-login—using Java Authentication and Authorization Service (JAAS)—has completed. If the customer creates a new profile, but the auto-login does not complete successfully, the customer is routed back to the login.jsp template and will not see the newusercreation.jsp template. After manual login, the customer is routed to the main.jsp template.

Note: If a customer had created a profile on a previous visit and logged in using the login.jsp template, the customer would simply be taken to the protected page the customer was trying to access.

From the newusercreation.jsp template, the customer can return to their shopping cart (shoppingcart.jsp), continue shopping, continue to the checkout process (shipping.jsp), view their order history (orderhistory.jsp), view their profile (viewprofile.jsp), view their payment history (paymenthistory.jsp), logout, or return to the main catalog page (main.jsp).

Note: The option to proceed to checkout is only provided on the newusercreation.jsp template if there are items in the customer's shopping cart.

This template is part of the sampleapp_user namespace in the Webflow.

Events

Every time a customer clicks a button to view more detail about an order, it is considered an event. Each event triggers a particular response in the default Webflow that allows them to continue. While this response can be to load another JSP, it is usually the case that an input processor and/or Pipeline is invoked first. Table  6-5 provides information about these events and the business logic they invoke.

Table 6-5 newusercreation.jsp Events

Event	Webflow Response(s)
link.shoppingcart	InitShoppingCartIP
button.checkout	InitShippingMethodListIP
link.home	GetTopCategoriesIP GetTopCategories Pipeline

 

newuserforward.jsp

The newuserforward.jsp template directs unregistered users to the newuser.jsp when that user clicks an ad placeholder that contains a static URI. This is necessary because dynamic URIs are not supported in placeholders. The newuserforward.jsp template then forwards the user to newuser.jsp. Additionally, the newuserforward.jsp bridges the transition from a non-secure to a secure connection (.http to .https).

Description

This template does not render a Web page or any other visible output. Its code is shown in Listing  6-18.

Listing 6-18 newuserforward.jsp Code

<% String s = com.bea.p13n.appflow.webflow.WebflowJSPHelper.
   createWebflowURL(pageContext, "sampleapp_main", "login.jsp",
   "button.createUser", true); %>

<% response.sendRedirect(s) ; %>

Table  6-6 shows the key template components.

Table 6-6 Template Components

Type of Component	Components
Included templates	None
Tag libraries	None
Imported Java packages	None

 

How newuserforward.jsp Works

The page prior to newuserforward.jsp can be any page that an anonymous user can access. However, this template is only needed if an unregistered user clicks the ad placeholder that prompts them to register. The static URI in the placeholder accesses the newuserforward.jsp which then forwards the user to the newuser.jsp template.

This template is part of the sampleapp_main namespace in the Webflow.

Events

The newuserforward.jsp template has one event, which triggers a particular response in the default Webflow that allows customers to continue. While this response can be to load another JSP, it is usually the case that an input processor or Pipeline is invoked first. Table  6-7 provides information about this event and the business logic it invokes.

Table 6-7 newuserforward.jsp Events

Event	Webflow Response(s)
button.createUser	newuser.jsp

 

usercreationforward.jsp

The usercreationforward.jsp template forwards new users to the newusercreation.jsp template after the registration and auto-login process using JAAS is completed by the Webflow. Once the user is created, the request must be flushed; the usercreationforward.jsp template allows that to happen.

Description

This template does not render a Web page or any other visible output. Its code is shown in Listing  6-19.

Listing 6-19 usercreationforward.jsp Code

<% String s = WebflowJSPHelper.createWebflowURL(pageContext,
   "sampleapp_user", "usercreationforward.jsp",
   "forward.usercreation", true); %>

<% response.sendRedirect(s) ; %>

The usercreationforward.jsp template uses Java classes in the com.bea.p13n.appflow.webflow.WebflowJSPHelper package and must include this import statement:

<%@ page import="com.bea.p13n.appflow.webflow.
   WebflowJSPHelper*" %>

How usercreationforward.jsp Works

The page prior to usercreationforward.jsp is the newuser.jsp template. When new users save their profiles, they are auto-logged in using JAAS and if the login is successful, because the old request must be flushed, the usercreationforward.jsp is needed to redirect the user to the newusercreation.jsp template.

This template is part of the sampleapp_user namespace in the Webflow.

Events

The usercreationforward.jsp template has one event. This event triggers a particular response in the default Webflow that allows customers to continue. While this response can be to load another JSP, it is usually the case that an input processor or Pipeline is invoked first. Table  6-8 provides information about this event and the business logic it invokes.

Table 6-8 usercreationforward.jsp Events

Event	Webflow Response(s)
forward.usercreation	newusercreation.jsp

 

Webflow Components Used in Visitor Self-Registration

The templates described in Implementing Customer Profile JSPs use Webflow components called input processors and pipelines to execute much of the necessary business logic to enable visitor self-registration. This section describes the key Webflow components implemented.

This section includes information on the following subjects:

• Input Processors

• Pipeline Components

Note: See Setting Up Portal Navigation for information about using, creating, or modifying a Webflow and using input processors and pipeline components.

Input Processors

The following input processors represent Java classes invoked to carry out more complex visitor regiatration tasks when invoked by the Webflow mechanism. These processors are:

• CustomerProfileIP

• LoginCustomerIP

For more information on input processors, see Types of Nodes.

CustomerProfileIP

CustomerProfileIP (all input processor names end in the letters "IP") processes the input of newuser.jsp and allows the customer to store their profile. It also creates and places a CustomerValue object into the Pipeline Processor session.

Class Invoked	examples.wlcs.sampleapp.customer.webflow. CustomerProfileIP
Required HTTPServletRequest Parameters (Personal Information)	HttpRequestConstants.CUSTOMER_FIRST_NAME HttpRequestConstants.CUSTOMER_MIDDLE_NAME HttpRequestConstants.CUSTOMER_LAST_NAME HttpRequestConstants.CUSTOMER_ADDRESS1 HttpRequestConstants.CUSTOMER_ADDRESS2 HttpRequestConstants.CUSTOMER_CITY HttpRequestConstants.CUSTOMER_STATE HttpRequestConstants.CUSTOMER_ZIPCODE HttpRequestConstants.CUSTOMER_COUNTRY HttpRequestConstants.CUSTOMER_HOME_PHONE HttpRequestConstants.CUSTOMER_BUSINESS_PHONE HttpRequestConstants.CUSTOMER_EMAIL HttpRequestConstants.CUSTOMER_EMAIL_OPT_IN (code location: newuser.jsp template.)
Required HTTPServletRequest Parameters (Demographic Information)	HttpRequestConstants.CUSTOMER_INCOME_RANGE HttpRequestConstants.CUSTOMER_EDUCATION_LEVEL HttpRequestConstants.CUSTOMER_DATE_OF_BIRTH HttpRequestConstants.CUSTOMER_GENDER HttpRequestConstants.CUSTOMER_OCCUPATION HttpRequestConstants.CUSTOMER_MARITAL_STATUS HttpRequestConstants.CUSTOMER_EMPLOYMENT_STATUS HttpRequestConstants.CUSTOMER_QUALITY (code location: newdemographictemplate.inc template.)
Required HTTPServletRequest Parameters (Shipping Information)	HttpRequestConstants.SAME_AS_ABOVE (code location: newuser.jsp template.)
	HttpRequestConstants.CUSTOMER_SHIPPING_ADDRESS1 HttpRequestConstants.CUSTOMER_SHIPPING_ADDRESS2 HttpRequestConstants.CUSTOMER_SHIPPING_CITY HttpRequestConstants.CUSTOMER_SHIPPING_STATE HttpRequestConstants.CUSTOMER_SHIPPING_ZIPCODE HttpRequestConstants.CUSTOMER_SHIPPING_COUNTRY HttpRequestConstants.DEFAULT_SHIPPING_ADDRESS (code location: newaddresstemplate.inc template.)
HTTPServletRequest Parameters (Payment Information)	HttpRequestConstants.CUSTOMER_CREDITCARD_TYPE HttpRequestConstants.CUSTOMER_CREDITCARD_HOLDER HttpRequestConstants.CUSTOMER_CREDITCARD_NUMBER HttpRequestConstants.CUSTOMER_CREDITCARD_MONTH HttpRequestConstants.CUSTOMER_CREDITCARD_YEAR HttpRequestConstants.CUSTOMER_CREDITCARD_ADDRESS1 HttpRequestConstants.CUSTOMER_CREDITCARD_ADDRESS2 HttpRequestConstants.CUSTOMER_CREDITCARD_CITY HttpRequestConstants.CUSTOMER_CREDITCARD_STATE HttpRequestConstants.CUSTOMER_CREDITCARD_ZIPCODE HttpRequestConstants.CUSTOMER_CREDITCARD_COUNTRY (code location: newcctemplate.inc template.)
Required HTTPServletRequest Parameters (Account Information)	HttpRequestConstants.USER_NAME HttpRequestConstants.PASSWORD HttpRequestConstants.CONFIRM_PASSWORD (code location: newuser.jsp template.)
Required Pipeline Session properties	None
Updated Pipeline Session properties	PipelineSessionConstants.CUSTOMER PipelineSessionConstants.PASSWORD PipelineSessionConstants.CREDITCARD_KEY (only if customer provides a credit card update).
Removed Pipeline Session properties	None
Validation	Checks that the required fields contain values and checks that the credit card number is not less than 16 digits (15 digits for AMEX type). Also checks that the password and confirm password fields contain matching values.
Exceptions	InvalidInputException, thrown when required fields are empty or credit card number is less than 16 digits (15 digits for AMEX type).

 

LoginCustomerIP

LoginCustomerIP processes the input of login.jsp and allows the customer to access the secure pages of the site. It also creates and places a CustomerValue object into the Pipeline Processor session.

Class Invoked	examples.wlcs.sampleapp.customer.webflow. LoginCustomerIP
Required HTTPServletRequest Parameters	None
Required Pipeline Session properties	PipelineSessionConstants.CUSTOMER PipelineSessionConstants.PASSWORD PipelineSessionConstants.CREDITCARD_KEY (only if the customer provides a credit card update).
Updated Pipeline Session properties	None
Removed Pipeline Session properties	PipelineSessionConstants.PASSWORD
Validation	Verifies that the username and password are correct.
Exceptions	InvalidInputException, thrown if either the username or password is invalid. ProcessingException, thrown if the username is invalid or cannot get authentication.

 

Pipeline Components

This section provides a brief description of each pipeline component associated with the Customer Login and Registration Services JSP template(s). These Pipelines are processor nodes a Webflow invokes to initiate the execution of specific tasks related to visitor registration.

Note: Some pipeline components extend other, base pipeline components. For more information on the base classes, see the Javadoc.

For more information on pipeline components, see Types of Nodes.

This section contains information on these pipeline components:

• RegisterUserPC

• EncryptCreditCardPC

RegisterUserPC

RegisterUserPC (all pipeline component names end in the letters "PC") retrieves the CustomerValue object and password from the Pipeline Processor session and creates a CUSTOMER attribute.

Class Name	examples.wlcs.sampleapp.customer.pipeline. RegisterUserPC
Contained in	CustomerProfile Pipeline
Required Pipeline Session Properties	PipelineSessionConstants.CUSTOMER PipelineSessionConstants.PASSWORD
Updated Pipeline Session Properties	None
Removed Pipeline Session Properties	PipelineSessionConstants.PASSWORD
Type	Java class
JNDI Name	None
Exceptions	PipelineException, thrown when the pipeline component cannot create the user.

 

EncryptCreditCardPC

EncryptCreditCardPC uses the CREDITCARD_KEY object to retrieve a customer credit card, encrypts the credit card number, and then adds the modified credit card back to the PipelineSession CustomerValue attribute.

Class Name	examples.wlcs.sampleapp.customer.pipeline. EncryptCreditCardPC
Description
Contained in	CustomerProfile Pipeline
Required Pipeline Session Properties	PipelineSessionConstants.CREDITCARD_KEY
Updated Pipeline Session Properties	PipelineSessionConstants.CUSTOMER
Removed Pipeline Session Properties	PipelineSessionConstants.CREDITCARD_KEY
Type	Java class
JNDI Name	None
Exceptions	PipelineException, thrown when the pipeline component cannot find the user in the Pipeline Processor session or the creditcard_key is invalid or the encryption did not complete successfully.