IBM® WebSphere® Commerce Multiple Approvals Reference Application

---

IBM® WebSphere® Commerce
Business Edition

Version 5.4

---

Last Updated: June 12, 2002

Introduction:

This reference application demonstrates an extended WebSphere Commerce 5.4 BE Approvals flow for the ‘User Self-Registration’ business process. This functionality would allow the User Registration transaction to be approved by multiple approvers, prior to being successful.

E.g. A user Self-Registers, depending on the Approvals role setup, his transaction may need to be approved by ApproverA, ApproverB, ... and ApproverN. (For implementation details refer to latter sections in this document).

Prerequisite Environment:

Operating System	Windows NT / 2000
Commerce Server	IBM WebSphere Commerce Business Edition 5.4
Application Server	WAS 4.x
WCS Database	IBM DB2 (with required fix-patches for WCS 5.4)

Installing the Reference Application:

To install this sample, you must first install and configure IBM WebSphere Commerce V5.4. Next, unzip the MultipleApprovalsRefApp.zip into a temp directory. Then locate the RefAppdriver-yyyymmdd.jar file in the packagedDriver directory and copy it to the system that has IBM WebSphere Commerce installed. Open a command prompt and ensure that java executable is in your path. Issue java -jar RefAppDriver-yyyymmdd.jar and provide the information that is requested.

The install utility is part of the driver. It is packaged into the driver jar file and can be run by issuing java -jar RefAppDriver-yyyymmdd.jar. The install utility source can be found in java/com/ibm/commerce/multipleapprovals/install/InstallDriver.java. At a high level the utility performs the following tasks:

• Unpackages the driver assets into their appropriate directories.
• Updates the commerce database with configuration information.

Examine this document for further information about what it does.

Restart your Commerce Server for the changes to take effect. You should also refer to the log files that were created in the logs directory in the IBM WebSphere Commerce root directory for any problems during the install.

Uninstalling the Reference Application:

To uninstall the Reference Application complete the following steps:

• Run the uninstallrefapp.bat, with the DatabaseName, DatabaseAdminID, DatabasePassword. E.g. uninstallrefapp mall db2admin myPassword. This will reset your database to original configuration.
• Manually delete the compiled class files under the “…\ \AppServer\installedApps\WC_Enterprise_App_demo.ear\lib\ com\ibm\commerce\multipleapprovals\commands” directory.
• Manually delete the MultipleApprovals_en_US.properties file under the “…\ \AppServer\installedApps\WC_Enterprise_App_demo.ear\properties” directory.

Building the sample:

Unzipping the MultipleApprovalsRefApp.zip would create the following directory structure for the build tree:

WCS_Ref_Apps
 buildjars
 MultipleApprovalsRefApp 
 driver
 ear
 lib 
 META-INF
 wcs
 bin
 schema
 xml
 java
 com
  ibm
 commerce
 multipleapprovals
  install
 commands
 Uninstall
 packagedDriver

Directory	Description	Contents
WCS_Ref_Apps	This is the root directory.	buildjars directory MultipleApprovalsRefApp directory Readme.htm
buildjars	This directory contains dependency JAR files that are used to build the Java™ source in this project. These JARs are taken from the current version of IBM WebSphere Application Server and IBM WebSphere Commerce.	ivjejb35.jar j2ee.jar wcsejbimpl.jar wcsejsclient.jar wcslogging.jar wcsmcruntime.jar wcsruntime.jar wcssfc.jar wcsbusinessflow.jar
MultipleApprovalsRefApp	This is the root directory for the sample application.	driver directory java directory Uninstall directory build.xml
driver	This directory contains the assets that will be built into the installable archive.	ear directory META-INF directory wcs directory
ear	This directory contains the assets that will be copied to the installed commerce enterprise archive directory.	lib directory properties directory
lib	The compiled class files are contained in this directory.	Compiled class files for Commands to be used by this application, in a qualified Directory structure: ApprovalMultipleSetUpRecordsCmdImpl.class HandleMultipleApprovalsCmdImpl.class
properties	This directory contains the property file that will be copied to the installed commerce enterprise archive directory.	MultipleApprovals_en_US.properties
driver/META-INF	This directory contains the MANIFEST.MF file for the driver JAR file.	MANIFEST.MF - indicates the Java class that should be invoked when the driver JAR is executed.
wcs	This directory contains assets that need to be installed in the root directory of IBM WebSphere Commerce.	bin directory schema directory
bin	Executables required to install and configure this application.	multipleApprovalsPopulatedb.db2.bat - This script populates the commerce database with configuration information. This script is used if the database is DB2 and the operating system is Windows.
schema	Assets required to populate the database.	xml directory.
schema/xml	Massloader XML document.	multipleApprovals.xml - Massloader import document used to populate the commerce database with configuration information for this application.
java	This directory contains the Java source.	Java source files are located in directories that model their package names.
Uninstall	The directory contains batch files to uninstall the reference application	uninstall.bat uninstall.sql.bat
packagedDriver	This directory contains the packaged driver.	The RefAppDriver-yyyymmdd.jar file is located in this directory.

The contents of this source tree are available in the attached MultipleApprovalsRefApp.zip file. This zip file excludes dependency jars found in the buildjars directory. In order to run the build, you will need to copy these jars from your installation of IBM WebSphere Commerce Business Edition and IBM WebSphere Application Server and place them in the buildjars directory. The first two can be found in the IBM WebSphere Application Server lib directory. The other jars can be found in the lib and wc.ear/lib directories in the IBM WebSphere Commerce root directory:

· ivjejb35.jar

· j2ee.jar

· wcsejbimpl.jar

· wcsejsclient.jar

· wcslogging.jar

· wcsmcruntime.jar

· wcsruntime.jar

· wcssfc.jar

· wcsbusinessflow.jar

Special attention should be paid to the build.xml document. This example uses Apache Ant to perform the build. Ant is a Java-based build tool like the make tool. The build.xml document contains the instructions that Ant uses to build the application. To run this build you will need to download a copy of Ant and ensure that the ant/bin directory is in your path. Then make the MultipleApprovalsRefApp directory your current directory and issue ant. (For more information about Ant refer to http://jakarta.apache.org/ant/index.html.) The build.xml document contains additional documentation on the build process. The basic build process is to compile the entire Java source into a lib directory in the driver/ear directory, then finally package the driver up into a jar file and place the jar in a directory called packagedDriver. Before you start the build you will need to ensure that java executable is in your path. You should ensure that the JDK you are using is the same as the one shipped with your version of IBM WebSphere Application Server.

Design and Implementation Overview

Objective:

To design and implement a reference demo application, demonstrating an extended WCS 5.4 BE Approvals Flow.

Current Business Flow:

Transactions may require that an individual approve some electronic marketplace actions before they proceed. This individual, called an approver, can accept or reject requests to perform a specific action. Approvals can be activated for the following WCS 5.4 BE business processes:

· Order Process

· User Registration

· Contract Submit

· RFQ Response

The current business flow is as follows (for User Self Registration):

· Respective Controller Command for the business process is invoked (e.g. UserRegistrationAdd).

· A Default implementation intervenes and starts the approval flow.

· An invoked PreApproval Task Command (e.g. UserRegistrationAddPreApproval) creates records, sets state to pending_approval and returns control to the default implementation.

· An invoked CheckApproval (e.g.. UserRegistrationAddCheckApproval) Task Command checks to determine if approval is required and returns control to the default implementation.

· Assuming CheckApproval returns Approval Required, relevant approvers are searched:

· If no approver group is found, an approval is not required; the state is changed from pending_approval to approved.

· If an approver group is found but is empty, exception is thrown.

· Otherwise the approvers are notified.

· Approvers logon to either approve or reject, this would invoke HandleApprovalsCmd. This command starts the default implementation flow, and this would invoke either:

o A PostApproval (e.g. UserRegistrationAddPostApproval) command, in which case the state is changed to approved; or

o A PostReject (e.g. UserRegistrationAddPostReject) command, in which case the state is changed to rejected.

· Control is returned to HandleApprovalsCmd.

Feature Scenario:

This demo application in addition to the ‘out-of-the-box’ approval scenarios, shall demonstrate Multiple Approvals functionality for the User Self-Registration process. This functionality would allow a transaction to be approved by multiple approvers, prior to being successful. E.g. A user Self-Registers, depending on the Approvals role setup, his transaction may need to be approved by ApproverA, ApproverB, ... and ApproverN.

Design:

This Demo Approval application is designed and packaged on top of WCS 5.4 BE, and incorporates Multiple Approval functionality.

The APRVSTATUS table for approvals Stores approval requests and their status. It contains multiple rows for each action awaiting approval, one row for every potential approver. Each entry is unique per approver, entity tuplet. FLOWTYPE_ID tells us which type of ENTITY_ID is pending approval.

Column Name	Column Type	Column Description
ACTIONTIME	TIMESTAMP NULL	When the approval record was acted on (that is, the time it was approved or rejected).
APPROVER_ID	BIGINT NULL	The ID of the user eligible to approve or reject the requested action.
APRVSTATUS_ID	BIGINT NOT NULL	Primary key.
COMMENTS	VARCHAR (254) NULL	Comments entered by approver during approval or rejection.
ENTITY_ID	BIGINT NOT NULL	Reference to the business object -- that is, which particular business object instance within the business object type specified by the FLOWTYPE_ID.
FLOW_ID	BIGINT NOT NULL	Reference to the flow for the steps in the approval process. Foreign key FLOW_ID.
FLOWTYPE_ID	BIGINT NOT NULL	Foreign key reference to the type of flow which determines the type of business object included in the approval. There are different IDs for each RFQ, Orders, User Registration, Contracts, Organization Registration and so on. Foreign key to FLOWTYPE_ID.
FLSTATEDCT_ID	BIGINT NOT NULL	Current state of the flow instance.
MBRGRP_ID	BIGINT NOT NULL	The ID of the Member Group to which the approver belongs making her an approver for this record.
STATUS	INTEGER NOT NULL	Approval status of this action:0 = pending, 1 = approved, 2 = rejected.
SUBMITTER_ID	BIGINT NOT NULL	ID of the user requesting the action which needs approval.
SUBMITTIME	TIMESTAMP NULL	The time that the action requiring approval was requested.

The default implementation incorporates a feature that allows for the flexible creation and alteration of business processes, this flow allows developers to modify the business flows across the various subcomponents of WebSphere Commerce.  The default implementation manages the Approval business flow, by making use of a State-Machine; this business flow, however, need not be modified to incorporate for the new multiple Approvals functionality.

A new controller command ‘HandleMultipleApprovalsCmdImpl’ is created, this command extends from the current HandleApprovalsCmdImpl and implements the HandleApprovalsCmd interface (mapped in the CMDREG table). This command would be triggered from within the WCS AdminConsole when an Approver either rejects or approves the request(s), and would incorporate the following business logic:

· Reject, in this case the HandleMultipleApproversCmd is called, it checks for the reject flag, and runs a super.performExecute() (HandleApprovalsCmd). This would then invoke the default implementation, set the request status to rejected = 2 (UserRegitrationAddPostRejectCmd) and delete other pending submissions sent to Approvers. Also the default implementation reaches completion and its State = rejected is set. Control is returned to HandleApprovals, success is judged, and control returned to HandleMultipleApprovalsCmd, this command then completes execution.

· Approve, in this case the HandleMultipleApproversCmd is called, it checks for the Approve flag. It fetches the multipleApprovalContant constant from the MultipleApprovals_en_US.properties file and checks if this is the last approval required for the submission. If it is not the last approval required, the command sets the Status of the Approval (for the particular Approver) as approved. However, if it is the last required approval, HandleApprovalsCmd is invoked with appropriate parameters. The default implementation is invoked, it sets the request status to approved = 1 (UserRegitrationAddPostApproveCmd) and deletes other pending submisions sent to Approvers. Also as the default implementation reaches completion and it’s State = rejected is set. Control is returned to HandleApprovals, success is judged, and control returned to HandleMultipleApprovalsCmd, this command then completes execution, and the finally the submitter is Approved.

Call-stack snapshot:

Also a task command ‘ApprovalMultipleSetupRecordsCmdmpl’ is created, this command extends from the current ApprovalSetupRecordsCmdmpl and implements the ApprovalSetupRecordsCmd interface. This command in addition to checking validity of the Approval request, and creates the approval record in the APRVSTATUS table. New added functionality includes the check for enough approvers being assigned. User self-registration is not allowed if enough approvers (=> multipleApprovalContant parameter) are not assigned, and an ECSystemException _ERR_NOT_ENOUGH_APPROVERS shall be thrown by the ApprovalMultipleSetupRecordsCmdImpl. The text for this exception message resides in the MultipleApprovals_en_US.properties file.

Note: This reference application is implemented for the User Self Registration business process only; however the code itself contains comments within logic to activate the multiple approval flow for other approvable business processes also.

Customizations to HandleMultipleApprovalsCmdImpl:

HandleMultipleApprovalsCmdImpl is the name of the controller command that processes approvals and rejections. This controller command was modified by extending the original implementation class and registering the new implementation class in the command registry. Refer to java/com/ibm.commerce/multipleapprovals/commands/HandleMultipleApprovalsCmdImpl.java for details on how the controller command was customized. Refer to schema/xml/ multipleApprovals.xml for details on how the new implementation was registered in the command registry.

The approver may either approve or reject one or more approval requests. The command will handle the updating of the APRVSTATUS table as well as any other activities required. The status of the approval requests record in the APRVSTATUS table will be updated to 1 for approved or 2 for rejected. The command treats each approval or rejection as a separate transaction so it is possible that if the command is invoked to process a batch of approvals or rejections, some may succeed and others may fail. Upon the last required approval or rejection super.performExecute() will be called hence raising a business flow event to handle each approval or rejection. The business flow event will handle the updating of the APRVSTATUS table as well as any other activities which have been defined for this transition.

The performExecute() method of the command contains the business logic for multiple approval handling. The current logic enables multiple approval flow for the User Registration business process, however by minor customization the functionality could be enabled for the flowing business processes:

· Order Process

· Contract Submit

· RFQ Response

Modifying conditions for the following ‘if’ block would allow for these business processes to be Multiple Approval enabled:

if (aprvFlag == 2 || !flowTypeIdentifier.equalsIgnoreCase(ApprovalConstants.EC_APPROVAL_FLOWTYPE_USER_REGISTRATION))

{

…..

…..

}

Customizations to ApprovalMultipleSetUpRecordsCmdImpl:

ApprovalMultipleSetUpRecordsCmdImpl is the name of the task command that creates an approval record for each potential approver of the action. This controller command was modified by extending the original implementation class and registering the new implementation class in the command registry. Refer to java/com/ibm.commerce/multipleapprovals/commands/ ApprovalMultipleSetUpRecordsCmdImpl.java for details on how the controller command was customized. Refer to schema/xml/ multipleApprovals.xml for details on how the new implementation was registered in the command registry.

This command incorporates added logic to check for enough approvers being assigned. User self-registration is not allowed if enough approvers (multipleApprovalContant parameter) are not assigned and an ECSystemException _ERR_NOT_ENOUGH_APPROVERS shall be thrown by the ApprovalMultipleSetupRecordsCmdImpl. The text for this exception message resides in the MultipleApprovals_en_US.properties file.

To enable this check for other business processes modify conditions to the following ‘if’ block found in the performExecute () method of the class:

if (approvers.length < multipleApprovalConstant && aRequest.getRequestName().equalsIgnoreCase(ApprovalConstants.EC_APPROVAL_FLOWTYPE_USER_REGISTRATION))

{

throw new ECSystemException(

notEnoughApproversEx,

getClass().getName(),

methodName,

ECMessageHelper.generateMsgParms(approverGroupName, orgId));

}

Customizations to the MultipleApprovals_en_US.properties file:

The MultipleApprovals_en_US.properties files is the resource bundle for the Multiple Approvals Application. The file contains the following two keys:

· HandleApprovals.multipleApprovalContant: the value of this is set to ‘2’, hence an approval request would require two approvers to approve the request. Changing the value of this variable would alter the number of approvals required for the reference application.

· _ERR_NOT_ENOUGH_APPROVERS: This holds the message to the error key corresponding to the exception, not enough approvers assigned. This message could be customized as per requirements, additional keys could be added to this file to handle exception conditions.

Customization to WCS published store:

The multiple approval reference application is independent to store logic, a published store is not required. However, a published Tooltech B2B store would help in understanding and utilizing the multiple approval flow functionality. The UserRegistrationNew.jsp provided with the Tooltech SAR handles exceptions thrown during user self registration; it provides with an excellent exception handling logic and does not have to be modified in order to make use of new functionality.

---

Trademarks and Service Marks

The following are trademarks or registered trademarks of IBM Corporation in the United States and other countries:

AIX      DB2      IBM     VisualAge(R) for Java      WebSphere

Java and all Java-based trademarks are trademarks of Sun Microsystems, Inc. in the United States, other countries, or both.

Windows, Windows NT and Windows 2000 are trademarks of Microsoft Corporation in the United States, other countries, or both.

Other company, product, or service names may be trademarks or service marks of others.

**************************************************************************

** © COPYRIGHT INTERNATIONAL BUSINESS MACHINES CORPORATION 2002

** ALL RIGHTS RESERVED.

**************************************************************************

Note to US Government Users -- Documentation related to restricted rights -- Use, duplication, or disclosure is subject to restriction set forth in GSA ADP Schedule Contract with IBM Corp.

End of document.

---