Skip Headers
Oracle® Fusion Middleware Developer's Guide for Oracle Adaptive Access Manager
11g Release 1 (11.1.1)

Part Number E15480-08
Go to Documentation Home
Home
Go to Book List
Book List
Go to Table of Contents
Contents
Go to Index
Index
Go to Master Index
Master Index
Go to Feedback page
Contact Us

Go to previous page
Previous
Go to next page
Next
PDF · Mobi · ePub

9 Customizing User Flow and Layout

The Struts/Tiles framework is used by OAAM to create a common look and feel for an application.

9.1 User Flows and Layout

The Struts configuration file struts-config.xml located in the WEB-INF directory defines all the navigation rules in the form of action definitions. The Tiles layout file tiles-def.xml located in the WEB-INF directory contains definitions for various pages.

To customize the OAAM user interface flow and the layout of the Java Server Pages (JSPs), you must override the OAAM Server JSP and struts action targets using the OAAM Extensions Shared library (oracle.oaam.extensions.war). The Extensions Shared Library contains the following two files to be used for the customizations:

Note:

Customizations should only be done in the OAAM Extensions Shared Library. Do not modify the struts-config.xml and tiles-def.xml files. Modifying the struts template is not recommended and would involve changes to both the template and the oaamLoginPage.jsp file.

9.1.1 Struts Actions

This section provides information about struts action definitions which are used to drive the user flow. OAAM action type classes are also summarized.

9.1.1.1 Action Definition

Action definitions typically contain path, type, and parameter attributes. The path defines what the URL will be. Many definitions also contain one or more forward elements that indicate which page should be displayed next. The login page example is shown.

<action path="/login" type="com.bharosa.uio.actions.LoginAction">
                      <forward name="success" path="/updateLoginStatus.do" redirect="true"/>
                      <forward name="loginJump" path="/loginJumpPage.jsp" redirect="true"/>
                      <forward name="password" path="password"/>
                      <forward name="challenge" path="/challengeUser.do" redirect="true"/>
                    </action>

9.1.1.2 Action Type

In login page example, the URL is http://<server name>/oaam_server/login.do. The login.do comes from the path definition of "/login."The type parameter defines the class that performs the action. The following classes are provided with the sample user pages.

Table 9-1 Action Type Classes

Class Name Description

com.bharosa.uio.actions.LoginAction

Updates the login status and, if appropriate, challenges the user.

com.bharosa.uio.actions.LoginFailAction

Displays error message in OAAM Server page. For example, the page could display a login blocked message.

com.bharosa.uio.actions.ActivityAction

Displays the confirmation message in OAAM Server page.

com.bharosa.uio.actions.PasswordAction

Updates the password status.

com.bharosa.uio.actions.UpdateAuthStatusAction

Updates the user authentication status and, if appropriate, it triggers pattern data processing.

com.bharosa.uio.actions.ValidateTrxAction

Validates the transaction

com.bharosa.uio.actions.FlashFingerprintAction

Fingerprints the device.

com.bharosa.uio.actions.LogoutAction

Logs out the user session and redirects to login page

com.bharosa.uio.actions.SignOnAction

Signs the user in

com.bharosa.uio.actions.RegisterQuestionsAction

Displays sets of questions which the user can choose and register the correct answer for each.

com.bharosa.uio.actions.ChangePasswordAction

Displays Change Password link

com.bharosa.uio.actions.ForgotPasswordAction

Displays Forgot Password link

com.bharosa.uio.actions.UserInputAction

Displays input fields

com.bharosa.uio.actions.UserPreferencesDoneAction

Displays message that user completed preference registration

com.bharosa.uio.actions.ChallengeUserAction

Challenges the user by displaying a question-pad with one of the questions already registered by the user

com.bharosa.uio.actions.ChangeUserNameAction

Changes the user name.

com.bharosa.uio.actions.MessageAction

Displays a message to the user

com.bharosa.uio.actions.ExitAction

Exits the user from the resource

com.bharosa.uio.actions.ErrorAction

Error occurs


9.1.2 Base Layout Definition

User interface pages are constructed using tiles in the Struts application. An external configuration file (/WEB-INF/tiles-def.xml) contains definitions for various pages.

The base layout "bharosa.uio.baseLayout" is defined to contain various sections. The header region is occupied by the customHeader.jsp page, the footer part is occupied by the customFooter.jsp page, and the body part by content. The following code shows the base layout.

<definition name="bharosa.uio.baseLayout" path="/bharosaUIOBaseLayout.jsp">
    <put name="header" value="/customHeader.jsp"/>
    <put name="footer" value="/customFooter.jsp"/>
    <put name="body" value="${body}"/>
  </definition>
 

To construct user interface pages, you define which JSP page should fill in the base layout in the tiles-def-extension.xml configuration file. The following example extends the baseLayout definition and uses a JSP named registerQuestionsHTML.jsp to render the content tile:

<definition name="registerQuestionsHTML" extends="bharosa.uio.baseLayout">
   <put name="body" value="/registerQuestionsHTML.jsp"/
  </definition>

Tile definition has the ability to extend another Tile definition. In the tiles-def.xml file, you can see that only the body region changes in the user flow.

9.1.3 How Struts and Tiles Work Together

To use Tiles in the Struts application, the following <plug-in> definition was added to the struts-config.xml file.

<!-- tiles plug-in -->
  <plug-in className="org.apache.struts.tiles.TilesPlugin">
    <set-property property="definitions-config" value="/WEB-INF/tiles-def.xml,/WEB-INF/tiles-def-extension.xml"/>
    <set-property property="definitions-debug" value="0"/>
    <set-property property="definitions-parser-details" value="0"/>
    <set-property property="definitions-parser-validate" value="true"/>
    <set-property property="moduleAware" value="true"/>
  </plug-in>

Action forward entries are in the struts-config.xml file. When an action is forwarded to the Tile definition baseLayout, then the base Layout jsp page will be displayed with corresponding jsp pages in the Tile definition. For example:

<action path="/updateForgotPasswordStatus" type="com.bharosa.uio.actions.UpdateAuthStatusAction" parameter="ForgotPassword">
      <forward name="success" path="/resetPassword.do" redirect="true" />
      <forward name="challenge" path="/challengeUserForgotPassword.do" redirect="true"/>
      <forward name="registerUser" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerQuestions" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerQuestionsHTML" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerUserInfo" path="/registerUserInfo.do" redirect="true"/>
      <forward name="signon" path="signon" redirect="true"/>
    </action>

The path attribute hold the value of the Tile definition to forward. When the path value is "/registerQuestions.do" the base layout jsp page is displayed with registerQuestionsHTML.jsp as the body as specified in tiles-def.xml.

<definition name="registerQuestionsHTML" extends="bharosa.uio.baseLayout">
   <put name="body" value="/registerQuestionsHTML.jsp"/
  </definition>

9.2 Custom User Flows and Layout Example

An example on how to customize the user flow and the look-and-feel of the graphical user interface is presented below.

9.2.1 Customize the Look-and-Feel

To customize the look and feel presented in the graphical user interface (GUI), add the custom JSP files to the OAAM Extensions shared library and then add the definitions to the tiles-def-extension.xml file.

The following example shows the definition for the password page, as defined in tiles-defs.xml:

<definition name="password" extends="bharosa.uio.baseLayout">
                    <put name="body" value="/password.jsp"/>
                  </definition>

At run time the password page dynamically displays all necessary GUI elements for the user to enter the required credential.

If the following definition is added to the tiles-def-extension file, the new customPassword.jsp is used anywhere that OAAM Server attempts to display the "password" page. The example below shows the definition of a custom password page that can be added to tiles-def-extension.xml:

<definition name="password" extends="bharosa.uio.baseLayout">
                    <put name="body" value="/customPassword.jsp"/>
                  </definition>

9.2.2 Customize the User Page Flows and Actions

To customize the user flows and actions, override the struts action classes and their mappings in the struts-config-extension.xml file.

The following example shows the definition for the login action, as defined in struts-config.xml:

<action path="/login" type="com.bharosa.uio.actions.LoginAction">
                      <forward name="success" path="/updateLoginStatus.do" redirect="true"/>
                      <forward name="loginJump" path="/loginJumpPage.jsp" redirect="true"/>
                      <forward name="password" path="password"/>
                      <forward name="challenge" path="/challengeUser.do" redirect="true"/>
                    </action>

The following example shows the possible values you could use to override the login action using struts-config-extension.xml:

<action path="/login" type="com.bharosa.uio.actions.CustomLoginAction">
                      <forward name="success" path="/updateLoginStatus.do" redirect="true"/>
                      <forward name="loginJump" path="/customLoginJumpPage.jsp"                                              redirect="true"/>
                      <forward name="password" path="password"/>
                      <forward name="challenge" path="/customChallengeUser.do" redirect="true"/>
                    </action>

9.3 tiles-def.xml File

This section shows a tiles-def.xml file.

<tiles-definitions>
 
  <!-- ========================================================== -->
  <!-- Master definition - Start                                  -->
  <!-- ========================================================== -->
  <!-- Main page layout used as a root for other page definitions -->
 
  <definition name="bharosa.uio.baseLayout" path="/bharosaUIOBaseLayout.jsp">
    <put name="header" value="/customHeader.jsp"/>
    <put name="footer" value="/customFooter.jsp"/>
    <put name="body" value="${body}"/>
  </definition>
 
  <definition name="bharosa.uio.messageLayout" path="/bharosaUIOMessageLayout.jsp">
    <put name="body" value="${body}"/>
  </definition>
 
  <!-- login success -->
 
  <definition name="loginSuccess" extends="bharosa.uio.baseLayout">
    <put name="body" value="/loginSuccess.jsp"/>
  </definition>
 
  <!-- login fail -->
  <definition name="loginFail" extends="bharosa.uio.baseLayout">
    <put name="body" value="/loginFail.jsp"/>
  </definition>
 
  <!-- password entry -->
  <definition name="password" extends="bharosa.uio.baseLayout">
    <put name="body" value="/password.jsp"/>
  </definition>
 
  <!-- register questions -->
  <definition name="registerInfo" extends="bharosa.uio.baseLayout">
    <put name="body" value="/registerInfo.jsp"/>
  </definition>
 
  <definition name="registerAuthenticator" extends="bharosa.uio.baseLayout">
    <put name="body" value="/registerAuthenticator.jsp"/>
  </definition>
 
  <definition name="registerQuestions" extends="bharosa.uio.baseLayout">
    <put name="body" value="/registerQuestions.jsp"/>
  </definition>
 
  <definition name="registerQuestionsHTML" extends="bharosa.uio.baseLayout">
    <put name="body" value="/registerQuestionsHTML.jsp"/>
  </definition>
 
  <definition name="registerUserInfo" extends="bharosa.uio.baseLayout">
    <put name="body" value="/registerUserInfo.jsp"/>
  </definition>
 
  <definition name="userPreferences" extends="bharosa.uio.baseLayout">
    <put name="body" value="/userPreferences.jsp"/>
  </definition>
 
  <definition name="registrationRequired" extends="bharosa.uio.baseLayout">
    <put name="body" value="/registrationRequired.jsp"/>
  </definition>
 
  <definition name="changePassword" extends="bharosa.uio.baseLayout">
    <put name="body" value="/changePassword.jsp"/>
  </definition>
 
  <definition name="forgotPassword" extends="bharosa.uio.baseLayout">
    <put name="body" value="/forgotPassword.jsp"/>
  </definition>
 
  <definition name="userInput" extends="bharosa.uio.baseLayout">
    <put name="body" value="/userInput.jsp"/>
  </definition>
 
  <!-- challenge User -->
  <definition name="challengeUser" extends="bharosa.uio.baseLayout">
    <put name="body" value="/challengeUser.jsp"/>
  </definition>
 
  <definition name="challengeUserForgotPassword" extends="bharosa.uio.baseLayout">
    <put name="body" value="/challengeUser.jsp"/>
  </definition>
 
  <definition name="challengeWait" extends="bharosa.uio.baseLayout">
    <put name="body" value="/challengeWait.jsp"/>
  </definition>
 
  <!-- qaExists -->
  <definition name="qaExists" extends="bharosa.uio.baseLayout">
    <put name="body" value="/qaExists.jsp"/>
  </definition>
 
  <!-- register qa done -->
  <definition name="questRegistered" extends="bharosa.uio.baseLayout">
    <put name="body" value="/registerQAdone.jsp"/>
  </definition>
 
  <!-- signon -->
  <definition name="signon" extends="bharosa.uio.baseLayout">
    <put name="body" value="/securityProfile.jsp"/>
  </definition>
 
  <!-- messages -->
  <definition name="message" extends="bharosa.uio.messageLayout">
    <put name="body" value="/message.jsp"/>
  </definition>
</tiles-definitions>

9.4 Struts Configuration File

This section shows a struts-config.xml file.

<struts-config>
 
  <!-- ========== Global Forward Definitions ============================== -->
 
  <global-forwards>
    <forward name="session_expired" path="/error.do?action=session_expired" redirect="true"/>
    <forward name="emptyLoginId" path="/error.do?action=empty" redirect="true"/>
    <forward name="fail" path="/error.do?action=fail" redirect="true"/>
    <forward name="invalid_user" path="/error.do?action=invalid_user" redirect="true"/>
    <forward name="error" path="/error.do?action=error" redirect="true"/>
    <forward name="block" path="/error.do?action=block" redirect="true"/>
    <forward name="challenge_block" path="/error.do?action=block" redirect="true"/>
    <forward name="cookieDisabled" path="/error.do?action=cookieDisabled" redirect="true"/>
    <forward name="accessDenied" path="/error.do?action=accessDenied" redirect="true"/>
    <forward name="invalid_request" path="/error.do?action=accessDenied" redirect="true"/>
    <forward name="user_disabled" path="/error.do?action=disabled" redirect="true"/>
    <forward name="wrong_answer" path="/error.do?action=wrong_answer" redirect="true"/>
    <forward name="login" path="/error.do" redirect="true"/>
  </global-forwards>
 
  <!-- ========== Action Mapping Definitions ============================== -->
  <action-mappings>
 
    <!-- action mappings for login -->
 
    <action path="/login" type="com.bharosa.uio.actions.LoginAction">
      <forward name="success" path="/updateLoginStatus.do" redirect="true"/>
      <forward name="loginJump" path="/loginJumpPage.jsp" redirect="true"/>
      <forward name="password" path="password"/>
      <forward name="passwordFT" path="password"/>
      <forward name="challenge" path="/challengeUser.do" redirect="true"/>
    </action>
 
    <action path="/loginFail" type="com.bharosa.uio.actions.LoginFailAction">
      <forward name="success" path="loginFail"/>
    </action>
 
    <action path="/activity" type="com.bharosa.uio.actions.ActivityAction">
      <forward name="success" path="loginSuccess" redirect="true"/>
    </action>
 
    <!-- validate password -->
 
    <action path="/password" type="com.bharosa.uio.actions.PasswordAction">
      <forward name="success" path="/exit.do"/>
      <forward name="invalid_user" path="/updateLoginStatus.do" />
      <forward name="noproxy" path="/updateLoginStatus.do"/>
      <forward name="resetPassword" path="/expiredPassword.do" redirect="true" />
    </action>
 
    <action path="/updateLoginStatus" type="com.bharosa.uio.actions.UpdateAuthStatusAction">
      <forward name="success" path="/exit.do"/>
      <forward name="challenge" path="/challengeUser.do" redirect="true"/>
      <forward name="registerUser" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerAuthenticator" path="/registerImage.do" redirect="true"/>
      <forward name="registerQuestions" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerQuestionsHTML" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerUserInfo" path="/registerUserInfo.do" redirect="true"/>
      <forward name="signon" path="signon" redirect="true"/>
    </action>
 
    <action path="/updateForgotPasswordStatus" type="com.bharosa.uio.actions.UpdateAuthStatusAction" parameter="ForgotPassword">
      <forward name="success" path="/resetPassword.do" redirect="true" />
      <forward name="challenge" path="/challengeUserForgotPassword.do" redirect="true"/>
      <forward name="registerUser" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerQuestions" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerQuestionsHTML" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerUserInfo" path="/registerUserInfo.do" redirect="true"/>
      <forward name="signon" path="signon" redirect="true"/>
    </action>
 
      <action path="/validateTrx" type="com.bharosa.uio.actions.ValidateTrxAction">
          <forward name="success" path="/exit.do"/>
          <forward name="challenge" path="/challengeUserTrx.do" redirect="true"/>
      </action>
 
    <action path="/flashFingerprint" type="com.bharosa.uio.actions.FlashFingerprintAction">
       <forward name="success" path="/flashFingerprint.jsp"/>
     </action>
 
      <!-- action mappings for logout -->
 
    <action path="/logout" type="com.bharosa.uio.actions.LogoutAction">
      <forward name="success" path="/loginPage.jsp" />
    </action>
 
    <!-- action mappings for signon -->
 
    <action path="/signon" type="com.bharosa.uio.actions.SignOnAction">
      <forward name="securityProfile" path="/securityProfile.jsp" redirect="true"/>
      <forward name="securityDone" path="/activity.do" redirect="true"/>
    </action>
 
    <!-- action mappings for security QA -->
 
    <action path="/registerQuestions" type="com.bharosa.uio.actions.RegisterQuestionsAction">
      <forward name="qaExists" path="qaExists" redirect="true"/>
      <forward name="registerAuthenticator" path="registerAuthenticator"/>
      <forward name="registerQuestions" path="registerQuestions"/>
      <forward name="registerQuestionsHTML" path="registerQuestionsHTML"/>
      <forward name="registerInfo" path="registerInfo"/>
      <forward name="registerUserInfo" path="registerUserInfo"/>
      <forward name="skip" path="/exit.do"/>
      <forward name="success" path="/exit.do"/>
    </action>
 
    <action path="/registerImage" type="com.bharosa.uio.actions.RegisterQuestionsAction" parameter="RegisterImage">
      <forward name="registerAuthenticator" path="registerAuthenticator"/>
      <forward name="success" path="/exit.do"/>
    </action>
 
    <action path="/registerUserInfo" type="com.bharosa.uio.actions.RegisterQuestionsAction" parameter="RegisterUserInfo">
      <forward name="registerUserInfo" path="registerUserInfo"/>
      <forward name="success" path="/exit.do"/>
    </action>
 
    <action path="/userPreferences" type="com.bharosa.uio.actions.RegisterQuestionsAction" parameter="UserPreferences">
      <forward name="registerAuthenticator" path="userPreferences"/>
      <forward name="registerInfo" path="userPreferences"/>
      <forward name="registerQuestions" path="registerQuestions"/>
      <forward name="registerQuestionsHTML" path="registerQuestionsHTML"/>
      <forward name="registerUserInfo" path="registerUserInfo" />
      <forward name="changePassword" path="/changePassword.do" />
      <forward name="success" path="userPreferences"/>
      <forward name="registrationRequired" path="registrationRequired"/>
      <forward name="exit" path="/exit.do" />
    </action>
 
    <action path="/changePassword" type="com.bharosa.uio.actions.ChangePasswordAction">
      <forward name="changePassword" path="changePassword" />
      <forward name="success" path="/userPreferences.do" redirect="true" />
      <forward name="exit" path="/exit.do" />
    </action>
 
    <action path="/resetPassword" type="com.bharosa.uio.actions.ChangePasswordAction" parameter="ResetPassword">
      <forward name="changePassword" path="changePassword" />
      <forward name="success" path="/exit.do" />
      <forward name="updateStatus" path="/updateLoginStatus.do" redirect="true" />
    </action>
 
    <action path="/expiredPassword" type="com.bharosa.uio.actions.ChangePasswordAction" parameter="ExpiredPassword">
      <forward name="changePassword" path="changePassword" />
      <forward name="success" path="/exit.do" />
      <forward name="updateStatus" path="/updateLoginStatus.do" redirect="true" />
    </action>
 
    <action path="/forgotPassword" type="com.bharosa.uio.actions.ForgotPasswordAction">
      <forward name="forgotPassword" path="forgotPassword" />
      <forward name="challenge" path="/challengeUserForgotPassword.do" />
      <forward name="success" path="/exit.do" />
      <forward name="noproxy" path="/updateForgotPasswordStatus.do" />
    </action>
 
    <action path="/getUserInput" type="com.bharosa.uio.actions.UserInputAction">
      <forward name="showAuthenticator" path="userInput" />
      <forward name="success" path="/exit.do" />
    </action>
 
 
    <action path="/userPreferencesDone" type="com.bharosa.uio.actions.UserPreferencesDoneAction">
      <forward name="success" path="/exit.do"/>
      <forward name="exit" path="/exit.do" />
    </action>
    <!-- action mappings for challenge user -->
 
    <action path="/challengeUser" type="com.bharosa.uio.actions.ChallengeUserAction">
      <forward name="success" path="/exit.do" />
      <forward name="challenge" path="challengeUser"/>
      <forward name="registerUser" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerAuthenticator" path="/registerImage.do" redirect="true"/>
      <forward name="registerQuestions" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerQuestionsHTML" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerUserInfo" path="/registerUserInfo.do" redirect="true"/>
      <forward name="wait" path="challengeWait"/>
    </action>
 
    <action path="/challengeUserTrx" type="com.bharosa.uio.actions.ChallengeUserAction" parameter="transaction">
      <forward name="success" path="/exit.do" />
      <forward name="challenge" path="challengeUser"/>
      <forward name="registerUser" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerAuthenticator" path="/registerImage.do" redirect="true"/>
      <forward name="registerQuestions" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerQuestionsHTML" path="/registerQuestions.do" redirect="true"/>
      <forward name="registerUserInfo" path="/registerUserInfo.do" redirect="true"/>
      <forward name="wait" path="challengeWait"/>
    </action>
 
    <action path="/challengeUserForgotPassword" type="com.bharosa.uio.actions.ChallengeUserAction" parameter="ForgotPassword">
      <forward name="success" path="/resetPassword.do" redirect="true"/>
      <forward name="forgotPassword" path="forgotPassword" />
      <forward name="challenge" path="challengeUserForgotPassword"/>
      <forward name="wait" path="challengeWait"/>
    </action>
 
    <action path="/changeUserId" type="com.bharosa.uio.actions.ChangeUserNameAction">
      <forward name="success" path="/exit.do" />
    </action>
 
    <!-- action mappings for message -->
 
    <action path="/message" type="com.bharosa.uio.actions.MessageAction">
      <forward name="success" path="message"/>
    </action>
 
    <action path="/exit" type="com.bharosa.uio.actions.ExitAction">
      <forward name="success" path="/empty.jsp"/>
    </action>
 
    <action path="/error" type="com.bharosa.uio.actions.ErrorAction">
      <forward name="login" path="/loginPage.jsp" redirect="true" />
    </action>
 
  </action-mappings>
 
  <!--The Tiles Request Processor for processing all the Tile requests-->
  <controller processorClass="org.apache.struts.tiles.TilesRequestProcessor"/>
 
  <!-- message resources -->
  <message-resources parameter="proxyweb" null="false"/>
 
  <!-- tiles plug-in -->
  <plug-in className="org.apache.struts.tiles.TilesPlugin">
    <set-property property="definitions-config" value="/WEB-INF/tiles-def.xml,/WEB-INF/tiles-def-extension.xml"/>
    <set-property property="definitions-debug" value="0"/>
    <set-property property="definitions-parser-details" value="0"/>
    <set-property property="definitions-parser-validate" value="true"/>
    <set-property property="moduleAware" value="true"/>
  </plug-in>
 
</struts-config>