At its most basic level, the order approval process consists of the following phases:
During checkout, the application determines if an order requires approval.
If the order requires approval, then an approver approves or rejects the order.
The application determines if the approval process for the order is complete.
If the approval process for the order is complete, then the order proceeds through checkout.
The following properties of an Order object (class atg.commerce.order.Order
) support the order approval process and maintain historical approval data for an order as it moves through these phases.
Property Name | Property Type | Description |
---|---|---|
| List | The list of profile IDs of the users who are authorized to approve the given order. |
| List | The list of system messages that the application attaches to the order. These messages indicate what conditions triggered an approval being required, such as “order limit exceeded.” They are defined by the processors in the |
| List | The list of one or more profile IDs of the users who have approved or rejected the order. |
| List | The list of messages the approvers attach to the order. The |
The following diagram illustrates the business logic that drives the order approval process and briefly indicates which components move an order from one step in the process to the next. The complete order approval process is subsequently explained in detail.
In this diagram, a customer has just submitted an order for checkout, and, consequently, the processOrder()
method has executed the processOrder
pipeline chain. processOrder
’s first processor, executeValidateForCheckoutChain
, has validated the order. processOrder
’s second processor, executeApproveOrderChain
, begins the order approval process by executing the approveOrder
chain. The first processor in the approveOrder
chain is verifyApproval
.
As is briefly illustrated in the preceding diagram, the order approval process is as follows:
approveOrder
’s first processor,verifyApproval
, checks whether the order already is approved.If the order is approved, then execution of
approveOrder
stops, and the order proceeds through the checkout process inprocessOrder
.If the order is not approved, then the order proceeds to the second processor in
approveOrder
.
approveOrder
’s second processor,runCheckRequiresApprovalChain
, executes a separate pipeline chain namedcheckRequiresApproval
.checkRequiresApproval
determines whether approval is needed for the order and reports back toapproveOrder
.If approval is needed, then the order continues through the
approveOrder
chain.approveOrder
changes the order’s state to PENDING_APPROVAL. The chain adds to the order’sauthorizedApproverIds
property the list of profile IDs of the users who are allowed to approve the order, and it adds to the order’sapprovalSystemMessages
property the conditions that triggered an approval to be required. Finally,approveOrder
sends out anApprovalRequired
message to the/Approval/Scenarios
JMS message topic. This message can then be used to execute scenarios.If approval is not needed, then execution of
approveOrder
stops, and the order proceeds through the checkout process inprocessOrder
. (For detailed information on theprocessOrder
pipeline, see Checking Out an Order in the Checking Out Orders section of the Configuring Purchase Process Services chapter.)
Note: The default implementation of the
checkRequiresApproval
chain checks theapprovalRequired
property in the customer’s profile. If theapprovalRequired
property is true, then approval is required for the customer. An error is then added to thePipelineResult
object, which tells the system that an approval is required, and the reason that approval is required is stored in theerrorMessages
property of the Order. This reason for approval is later added to the order’sapprovalSystemMessages
property by theapproveOrder
chain’saddApprovalSystemMessagesToOrder
processor. If theapprovalRequired
property is false, then approval is not required for the customer.You can edit the
checkRequiresApproval
chain to create specific requirements for whether an approval is required for a given customer. For example, you might want to include a processor that checks the total amount of the customer’s order against an order limit specified in the customer’s profile. If the order amount exceeds the specified limit, then approval for the customer’s order would be required. Similarly, you might want to include a processor that checks the manufacturers of the items in the customer’s order against a list of preferred suppliers specified in the customer’s profile. If a manufacturer is not in the list of preferred suppliers, then approval for the customer’s order would be required.If approval for the order is needed, an approver then approves or rejects the order and submits this decision in a form using the
ApprovalFormHandler
form handler. The form’s “Approve” and “Reject” submit buttons call thehandleApproveOrder
method or thehandleRejectOrder
method, respectively.If the
handleApproveOrder
method is called, the method executes theorderApproved
pipeline chain.orderApproved
adds the profile ID of the user who approved the order to the order’sapproverIds
property, and adds the messages associated with the approver’s decision to the order’sapproverMessages
property. Finally,orderApproved
sends out anApprovalUpdate
message whoseapprovalStatus
property is set to “approved.” This message is sent to both the/Approval/ApprovalUpdate
JMS message queue and the/Approval/Scenarios
JMS message topic. This message can then be used to execute scenarios.If the
handleRejectOrder
method is called, the method executes theorderRejected
pipeline chain.orderRejected
adds the profile ID of the user who rejected the order to the order’sapproverIds
property, and adds the messages associated with the approver’s decision to the order’sapproverMessages
property. Finally,orderRejected
sends out anApprovalUpdate
message whoseapprovalStatus
property is set to “rejected.” This message is sent to both the/Approval/ApprovalUpdate
JMS message queue and the/Approval/Scenarios
JMS message topic. This message can then be used to execute scenarios.
Note: The
orderApproved
andorderRejected
pipeline chains are the same with the exception of the value ofapprovalStatus
property of theApprovalUpdate
message that is sent. You can edit these chains to add or remove functionality to meet your application’s needs.The
ApprovalCompleteService
, located in Nucleus at/atg/commerce/approval/ApprovalCompleteService
, is configured to listen for theApprovalUpdate
messages sent by theorderApproved
andorderRejected
chains to the/Approval/ApprovalUpdate
JMS message queue. WhenApprovalCompleteService
receives a message, it executes thecheckApprovalComplete
pipeline chain.checkApprovalComplete
determines whether the approval process for the order is complete. By default,checkApprovalComplete
’s second processor,approvalCompleteAnalyzer
, checks whether at least one person has approved or rejected the order. If so, then the approval process for the order is considered to be complete.If at least one person has approved the order,
checkApprovalComplete
changes the order’s state from PENDING_APPROVAL to APPROVED and executes theprocessOrder
chain so the order can go through the checkout process. (For detailed information on theprocessOrder
pipeline, see Checking Out an Order in the Checking Out Orders section of the Configuring Purchase Process Services chapter.) Additionally, thecheckApprovalComplete
chain sends anApprovalComplete
message whoseapprovalStatus
property is set to “approval_passed
” to the/Approval/Scenarios
JMS message topic. This message can then be used to execute scenarios.If at least one person has rejected the order,
checkApprovalComplete
changes the order’s state from PENDING_APPROVAL to FAILED_APPROVAL, and sends anApprovalComplete
message whoseapprovalStatus
property is set to “approval_failed
” to the/Approval/Scenarios
JMS message topic. This message can then be used to execute scenarios.
Note: As previously mentioned, the default implementation of the
approvalCompleteAnalyzer
processor merely checks whether at least one person has approved or rejected the order. If so, then the approval process for the order is considered completed. You can change the implementation ofapprovalCompleteAnalyzer
in order to change the requirements for completion of the approval process.
For detailed information about the pipeline chains and processors mentioned in this section, refer to Appendix F, Pipeline Chains.