Customer enactment in WebSphere Commerce with APIs

Customer support in Madisons

IBM® WebSphere® Commerce provides APIs that allow administrators to perform customer enactment in the system. Learn how you can leverage these APIs to implement customer enactment in a Madisons store with little customization. The article also exposes the order locking concept and its behavior in the customer enactment flow.

Ashish Deshpande (ashisdes@in.ibm.com), Solution Architect, IBM

Photo of Ashish DeshpandeAshish Deshpande is a Solution Architect with the Rapid Solutions Center, Industry Solutions team at the IBM India Labs. Ashish has several years of experience with WebSphere Commerce, consisting of solution design, implementation, and consulting. He also conducted WebSphere Commerce boot camp training programs for IBM partners in the Asia pacific region. He is a certified SOA solution designer.



14 February 2014

Also available in Chinese

Introduction

The customer enactment term refers to a process in which the customer service representative (CSR) is empowered to assume the identity of the customer/shopper to carry out certain operations on behalf of them. These customers are the registered shoppers in the system. The customer enactment term can be used interchangeably with guided shopping.

WebSphere Commerce provides business user tools (WebSphere Commerce Accelerator and Sales Center), whereby CSRs manage inquiries from potential customers. However, these tools are different applications and look different from the storefront application that the shoppers use for shopping purposes. Although the adoption of these tools to carry out CSR operations is common, some businesses want to leverage the storefront experience to provide customer support to their customers. Some primary drivers for using a storefront to provide customer support include:

  • Promoting consistent UI across users
  • Enabling CSRs to view what shoppers see on the storefront so that they can improve the turnaround time of the incident
  • Assisting shoppers while they are shopping on the site

This article showcases how the Madisons storefront can be leveraged for customer support operations.

Customer enactment

The customer enactment process allows CSRs to perform various operations, such as:

  • Modifying a shopper's profile information
  • Reviewing order information
  • Reviewing discounts that are calculated on the order
  • Reviewing the status of coupons
  • Modifying the order that is being worked on by the shopper

WebSphere Commerce provides APIs to accomplish the customer enactment scenario. An administrator can act on behalf of a registered customer for multiple requests in a session by running the RunAsUserSetInSession URL. If an administrator has the required authority to act on behalf of a registered customer, the administrator can assume the identity for that customer for all subsequent requests. By default, the administrator who acts on behalf of a registered customer can perform all actions that the registered customer can perform. However, while the administrator acts on behalf of a registered customer, the administrator cannot run any administrative commands.

After the RunAsUserSetInSession URL successfully switches the administrator's identity to the identity of a registered customer, WebSphere Commerce:

  • Sets the user ID associated with the current request to the specified customer's ID
  • Causes the command context to recompute values, such as the customer's active organization
  • Causes all subsequent commands (until the switch is reversed) to include the customer's identity and active organization into the administrator's session information
  • During every subsequent request, extracts the customer's identity and active organization from the administrator's session

Before WebSphere Commerce allows the administrator to run a command under the customer's identity, it ensures that the administrator has the required authorization to do so. WebSphere Commerce:

  • Checks if the customer is registered in the administrator's authorization domain
  • Checks that the command is defined in the forUser access control policies
  • Checks to see whether the customer can execute the command

To switch back to the administrator's original identity, the administrator runs the RestoreOriginalUserSetInSession URL. This command removes the customer's information from the administrator's session and restores the administrator's session information to the state prior to switching to the customer's identity.

Order locking

The order entity goes through various states during the checkout process and it has direct implications on the monetary amount of the order. Therefore, unlike other entities, it is guarded by something that is called order locking in WebSphere Commerce. As a retailer, you might allow the CSR and the shopper to update the shopper's profile at the same time. However, you might not want to allow the CSR and the shopper to update the shopper's order at the same time. So let's explore more about order locking.

An order lock prevents multiple users from editing an order at the same time. When the first user starts to edit an order, the order is locked. If other users try to edit that same order, they receive a message to indicate that they cannot edit the order. By default, order locking is enabled.

You can disable order locking by making changes to the commerce instance configuration file. Allowing multiple users to work on the same order simultaneously can cause data integrity issues and, therefore, needs to be handled carefully.

In this customization, you are not going to disable the order locks; you retain the default order locking settings. However, you need to understand how the system would allow the shopper and the CSR to work on the same order while order locking is in place.

APIs

Following are the APIs that you are going to use in this implementation. Each of these components is described in detail.

  • RunAsUserSetInSession - Allows administrators with the required authority to run subsequent commands in the same session under a specified customer's identity. The access control framework checks that the current user belongs to one of the following roles:
    • Customer service representative (CSR)
    • Customer service supervisor (CSS)
    • Operations manager
    • Sales manager
    • Seller

    The parameter values are:

    • langId
    • URL - The URL to be called when the command completes successfully
    • storeId
    • runAsUserId - The registered customer's user ID, which is the customer under whom subsequent requests run

    Sample URL: https://hostname/webapp/wcs/stores/servlet/RunAsUserSetInSession?runAsUserId=32005 &URL=UserAccountView

  • RestoreOriginalUserSetInSession - Resets the session for subsequent commands so they revert to the original administrator user ID after an administrator establishes the runAsUser value in the session by running the RunAsUserSetInSession command.

    The parameter values are:

    • langId
    • URL - The URL to be called when the command completes successfully
    • storeId

    Sample URL: https://hostname/webapp/wcs/stores/servlet/RestoreOriginalUserSetInSession?storeId=11001&URL=AjaxLogonForm&myAcctMain=1

  • AdvancedOrderEditBegin - Sets up an order for editing, or changes and begins an edit session. It attaches an editor ID to the order. This URL checks whether the order and order items are editable. If they are editable, it changes the status to E unless the state is NEW, P, or E. Meanwhile, if the order and order items are in a shopping cart, no status change is made. Orders that have already been submitted can be changed before they are released to fulfillment.

    The parameter values are:

    • orderId
    • URL - The URL to be called when the command completes successfully
    • storeId

    Sample URL: http://hostname/webapp/wcs/stores/servlet/AdvancedOrderEditBegin?orderId=13502&URL=StoreView

  • AdvancedOrderEditEnd - Closes an order for editing and removes the editor ID from the order. That is, this URL removes the EDITOR_ID values from the order in the ORDERS table. The AdvancedOrderEditEnd URL can be used to close the editing of an order only if the order is in the NEW, P, or E state. The major status will not change after the invocation.

    The parameter values are:

    • orderId
    • URL - The URL to be called when the command completes successfully
    • storeId

    Sample URL: http://hostname/webapp/wcs/stores/servlet/AdvancedOrderEditEnd?orderId=13502&URL=StoreView

  • OrderLockingHelper - A helper class that implements a few methods to do the order resource locking and unlocking.

Customization steps

The customer enactment process starts with a customer search. The current Madisons store does not have a customer search feature that can be leveraged by CSRs to carry out the enactment. Therefore, you are going to make a provision for CSRs in a Madisons store to search for a customer and then perform enactment for the selected customer. The other aspect of the customization is to handle order locking during enactment.

To work on the order that is created by the shopper, the CSR needs to acquire a lock on that order. Similarly, the CSR needs to release the lock when the order modification is complete. As mentioned in the APIs section, the AdvancedOrderEditBeginCmd and AdvancedOrderEditEndCmd commands provide these operations. However, these commands have one limitation. The only user who can release the lock on the order is the user who acquired the lock on that order. If other CSRs attempt to acquire or release the lock, these commands fail. However, in a real world scenario, this limitation might not be acceptable. The business would probably want to allow all authorized CSRs to remove the lock on the order, irrespective of who locked that order, so that the shopper can continue to work on that order. Your customization makes sure of exactly that. It would first check whether the order is locked. If it is locked, it unlocks the order and then allows the CSR to release the lock on the order.

All the views and commands that are developed for this customization can be invoked by users with a customer service role only. The access control policies ensure the same. You can review the same in the attached source.

UI customization

The Madisons starter store provides all the pages and features necessary for a functioning consumer direct online store. This section introduces the customizations that are required in the Madisons storefront.

Customer search

To allow the CSR to perform customer enactment, the first step is to make provision for the CSRs to search for a customer. So you are going to build a new Customer Search page that can be executed by only the CSRs.

  1. Create a JSP called CustomerSearchDisplay.jsp, as shown in Listing 1. This JSP displays the search form. Register this view in the struts configuration extension file. The CustomerSearchView allows the CSRs to search for a customer.
    Listing 1. CustomerSearchDisplay.jsp
    <action path="/CustomerSearchView" 
    type="com.ibm.commerce.struts.BaseAction">
    <set-property property="credentialsAccepted" value="<storeId>:P "/>
    </action>
    
    <forward className="com.ibm.commerce.struts.ECActionForward" 
    name="CustomerSearchView/<storeId>" 
    path="/UserArea/AccountSection/UserCustomSearchDisplay.jsp"/>
  2. Load the access control policy by running the acpload command.

Customer search results

The search results page displays after the CSR submits a search.

  1. Create a JSP called CustomerSearchResultsDisplay, as shown in Listing 2. This JSP renders the search results. It calls the Person service to retrieve the customer details. It also allows the CSR to select the customer from the search results for enactment. The CSR clicks the Start Enactment button. Register this view in the struts configuration extension file.
    Listing 2. CustomerSearchResultsDisplay.jsp
    <action path="/CustomerSearchResultsView"
    type="com.ibm.commerce.struts.BaseAction">
    <set-property property="credentialsAccepted" value="<storeId>:P "/>
    </action>
    
    <forward className="com.ibm.commerce.struts.ECActionForward" 
    name="CustomerSearchResultsView/<storeId>" 
    path="/UserArea/AccountSection/CustomSearchResultsDisplay.jsp"/>
  2. Load the access control policy by running the acpload command.

Header links

The header menu contains the store logo with category listings beneath it on the left side. On the right side, the header provides a search field and displays the mini shopping cart beneath it. There are various links located between the search field and the mini shopping cart, such as Shopping Cart, Advanced Search, and Sign Out. Let's add a Customer Search link before the Sign Out link.

  1. Add the Customer Search navigation link in the header so that the CSR can navigate to the Customer Search page. This link is available to only the customer service user roles.
  2. Similarly, create a new link in the header that would terminate the enactment process. You can call this link Drop Customer Session. When the enactment is active, the user can click on this link to drop the enactment. It is important to note that the Customer Search option is not available to the CSR until the CSR drops the enactment. The idea is to first finish the enactment and then move on to the next customer search. To make these changes, modify the existing extension header JSP called CachedHeaderDisplayExt.jspf, as shown in Listing 3.
    Listing 3. CachedHeaderDisplayExt.jspf
    <wcbase:useBean id="eBean" 
    classname="com.ibm.commerce.sample.beans.MyCompanyEnactmentDataBean">
    </wcbase:useBean>
    
    <c:if test="${eBean.CSRActive}">
    	<wcf:url var="CustomerSearchURL" value="CustomerSearchView" >
             <wcf:param name="langId" value="${langId}" />
             <wcf:param name="storeId" value="${WCParam.storeId}" />
             <wcf:param name="catalogId" value="${WCParam.catalogId}" />
    	</wcf:url>
    	
    	<span><a href='<c:out value="${CustomerSearchURL}"/>' ><fmt:message 
    key="TITLE_CUSTOM_SEARCH" bundle="${storeText}" /></a>
    	</span>
    	<fmt:message key="DIVIDING_BAR" bundle="${storeText}" />
    </c:if>

    As you can see, this JSP fragment relies on the databean to figure out whether:

    • The enactment is active or not.
    • The logged-in user possesses the customer service role.
  3. Create a smart databean that is called MyCompanyEnactmentDataBean and implement the logic that would determine whether the enactment is active. Review the code from the attached source.

Business logic customization

You can add new business logic before, after, or both before and after existing business logic. Here, you are adding the logic before RunAsSetInSession to ensure that the orders are unlocked before being worked on by the CSRs. Similarly, you need to add the logic to unlock the orders that are locked after the session is restored by the CSRs.

Order unlocking

An order lock prevents multiple users from editing an order at the same time. You need to ensure that the user's order is unlocked before it is taken up for work by the CSR.

  1. Create a command called MyCompanyExtAdvancedOrderEditBeginCmd that extends the AdvancedOrderEditBeginCmd command. Implement the logic (shown in Listing 4) in the performExecute() method.
    Listing 4. Unlocking order
    OrderLockingHelper helper = new OrderLockingHelper ();
    if(helper.isLocked(orderId)) {
       Logger.log("The Order is currently locked by " + 
    helper.getLockedByLogonId(orderId));
       helper.lock(orderId, true);
       Logger.log("Order is now locked by  " + getCommandContext().getUserId());
       super.performExecute();
    }
  2. Register this command implementation in CMDREG. You need to update the CMDREG entry, as shown in Listing 5.
    Listing 5. Register MyCompanyExtAdvancedOrderEditBeginCmd command in CMDREG
    update cmdreg set 
    classname='com.ibm.commerce.sample.commands.MyCompanyExtAdvancedOrderEditBeginCmdIm
    pl' where 
    interfacename='com.ibm.commerce.ordermanagement.commands.AdvancedOrderEditBeginCmd' 
    and storeent_id=0;

Enactment command

You need a new controller command that would work as an enactment command. It is invoked when the CSR clicks Start Enactment on the Customer Search page.

  1. Create a controller command called MyCompanyEnactmentCmd. The enactment logic includes:
    • Finding the pending order of the user
    • Invoking AdvancedOrderEditBeginCmd for the pending order
    • Invoking RunAsSetInSession URL to initiate the enactment
    • Redirecting the user to the Home page

    It is important to note that the AdvancedOrderEditBeginCmd command can be invoked by only users with a customer service role. In other words, this command will fail if it is invoked after the enactment. So you need to make sure that it is called before the RusAsUserSetInSession command.

  2. Register the MyCompanyEnactmentCmd command in CMDREG, as shown in Listing 6.
    Listing 6. Register the MyCompanyEnactmentCmd command in CMDREG
    insert into CMDREG (STOREENT_ID, INTERFACENAME, DESCRIPTION, CLASSNAME, 
    TARGET) values (0,'com.ibm.commerce.sample.commands.MyCompanyEnactmentCmd', 
    'This is a new controller command for enactment.', 
    'com.ibm.commerce.sample.commands.MyCompanyEnactmentCmdImpl','Local');
  3. Create the struts action mapping for the MyCompanyEnactmentCmd command.
  4. Load the access control policy by running the acpload command.

Session termination command

The session termination command is required to restore the session and unlock the order so that a shopper can continue to work on this order.

  1. Create a controller command called MyCompanyEnactmentEndCmd. It is invoked when the CSR clicks the Drop Customer Session link that is displayed in the header section of the page. The link first invokes the RestoreOriginalUserSetInSession command, which in turn redirects the request to this command. This command cannot be invoked during enactment, so you must terminate it first by calling the Restore command.
  2. The command is required to unlock the order if it was locked during enactment.
    • Read the enactedUserId and find the pending order of the user. If it is locked by the current user, then call the AdvancedOrderEditEndCmd command.
    • Redirect the user to the Home page.
  3. Register the MyCompanyEnactmentEndCmd command in CMDRE, as shown in Listing 7.
    Listing 7. Register the MyCompanyEnactmentEndCmd command in CMDRE
    insert into CMDREG (STOREENT_ID, INTERFACENAME, DESCRIPTION, CLASSNAME, TARGET) 
    values (0,'com.ibm.commerce.sample.commands.MyCompanyEnactmentEndCmd', 'This is a 
    new controller to terminate the enactment.', 
    'com.ibm.commerce.sample.commands.MyCompanyEnactmentEndCmdImpl','Local');
  4. Create the struts action mapping for the MyCompanyEnactmentEndCmd command.
  5. Load the access control policy by running the acpload command.

Run the business scenario

This section outlines two business scenarios. The first scenario shows the CSR working on a pending order that is created by the customer. In the second scenario, the CSR helps the customer to edit the customer's profile information and to create an order.

Scenario 1

The CSR works on a pending order that is created by the customer. The CSR and the shopper log in and attempt to modify the same order simultaneously.

  1. Build the project and restart the server.
  2. Launch a Firefox session and navigate to the Madisons home page. Log in as a registered user and add items to the cart. Leave the browser session open.
    Figure 1. Shopper logs in
    A smaller Madisons screenshot showing items displayed in the shopping cart.

    Click to see larger image

    Figure 1. Shopper logs in

    A Madisons screenshot showing items displayed in the shopping cart.
  3. Launch Internet Explorer and navigate to the Madisons home page. Log in as a CSR. If you do not have a CSR profile, you can create one in the Organization Administration Console.
    Figure 2. CSR logs in
    Shows a smaller screenshot of a Madisons page after a CSR logs in

    Click to see larger image

    Figure 2. CSR logs in

    Shows a screenshot of a Madisons page after a CSR logs in
  4. Click the Customer Search link in the header. The Customer Search form displays, as shown in Figure 3.
    Figure 3. CSR - Customer search
    A smaller Madisons screenshot showing the Customer Search link and the Customer Search input fields

    Click to see larger image

    Figure 3. CSR - Customer search

    A Madisons screenshot showing the Customer Search link and the Customer Search input fields
  5. Use the Customer Search form to search for a customer in the system. The search action displays the matching customers in the Customer Search Results screen, as shown in Figure 4.
    Figure 4. Customer search results
    A smaller Madisons screenshot showing the results of the customer search

    Click to see larger image

    Figure 4. Customer search results

    A Madisons screen showing the results of the customer search
  6. Select the customer and click Enact Customer. Observe the header in Figure 5. The Customer Search link is not visible anymore and the Drop Customer Session link is displayed instead.
    Figure 5. CSR enacts customer
    A smaller Madisons screenshot showing that the Customer Search link has been replaced by the Drop Customer Session link

    Click to see larger image

    Figure 5. CSR enacts customer

    A Madisons screen showing that the Customer Search link has been replaced by the Drop Customer Session link
  7. Navigate to the shopping cart page.
  8. Make changes to the order in Internet Explorer by adding items to the cart, as shown in Figure 6.
    Figure 6. CSR modifies customer's order
    A smaller image showing the Shopping Cart page with additional items that were added by the CSR

    Click to see larger image

    Figure 6. CSR modifies customer's order

    Shows the Shopping Cart page with additional items that were added by the CSR
  9. Now, you can try making changes to the same order from a shopper’s browser session. You see an error, as shown in Figure 7. The error appears because the order is locked by the CSR.
    Figure 7. Customer attempts to modify order
    A smaller image showing an error on the Shopping Cart page because the customer attempted to modify the order that is currently locked by the CSR

    Click to see larger image

    Figure 7. Customer attempts to modify order

    Shows an error on the Shopping Cart page because the customer attempted to modify the order that is currently locked by the CSR
  10. When you finish making changes to the order in Internet Explorer, click Drop Customer Session, as shown in Figure 8.
    Figure 8. CSR drops enactment
    A smaller Madisons screenshot with an arrow indicating the location of the 'Drop Customer Session' link

    Click to see larger image

    Figure 8. CSR drops enactment

    The Madisons screen with an arrow indicating the location of the 'Drop Customer Session' link

    The enactment is dropped and the session is restored, as shown in Figure 9.

  11. Navigate to the Firefox session where you logged in as a shopper and refresh the cart. You should be able to see the changes made by the CSR. Try making changes to the order as a shopper now. You should be able to make changes and place an order.
    Figure 9. Customer modifies order
    A smaller screenshot showing the shopping cart from the shopper's Mozilla Firefox session

    Click to see larger image

    Figure 9. Customer modifies order

    A screenshot showing the shopping cart from the shopper's Mozilla Firefox session

Scenario 2

The CSR modifies the customer's profile information.

  1. The customer logs in to the store and does not have a pending order in the system.
  2. The CSR logs in and enacts the customer. It is important to note that because a pending order does not exist, the CSR cannot lock the order. However, the CSR can perform other activities, such as updating profile information.
  3. The customer adds an item to the cart and creates the pending order.
  4. The CSR refreshes the cart and sees the pending order. However, currently, the CSR cannot make changes to the order because the lock was not acquired during enactment. If the CSR attempts to make any changes to the order, an error is displayed, as shown in Figure 10.
    Figure 10. CSR sees order lock error
    Shows a smaller screenshot of the pending order that displays an error message which states that the order is not locked by you, the CSR.

    Click to see larger image

    Figure 10. CSR sees order lock error

    Shows a screenshot of the pending order that displays an error message which states that the order is not locked by you, the CSR.
  5. To acquire a lock on this pending order, the CSR needs to click Drop Customer Session and re-enact the customer.

Security

The CSRs are privileged users and usually perform business operations over the intranet; that is, inside the firewall by accessing out-of-the-box business user tooling. The feature explained in this article empowers the CSRs to access the storefront URLs and run the administrative commands over the internet. While this access control practice might not be a problem for many customers, it is advised that you evaluate and discuss it with your security team before you implement this feature.

Aurora

This feature can also be introduced in the Aurora starter store. The business logic remains the same. However, minimal customization would be required in the JSPs.

Conclusion

This article explained the development of the customer support feature in the Madisons starter store. You also learned how to leverage the order locking feature when the CSR and the shopper attempt to edit the same order simultaneously. This article is useful to enterprises who want to leverage the WebSphere Commerce storefront UI to carry out customer operations.


Download

DescriptionNameSize
Sample code for customer enactment.CustEnactWC_samplecode.zip47KB

Resources

Learn

Get products and technologies

  • Download IBM WebSphere products including WebSphere Transformation Extender Design Studio, version 8.4.0.2 or later.
  • Evaluate IBM products in the way that suits you best: Download a product trial, try a product online, use a product in a cloud environment, or spend a few hours in the SOA Sandbox learning how to implement Service Oriented Architecture efficiently.

Discuss

  • Get involved in the My developerWorks community. Connect with other developerWorks users while exploring the developer-driven blogs, forums, groups, and wikis.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Commerce on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Commerce, WebSphere
ArticleID=962723
ArticleTitle=Customer enactment in WebSphere Commerce with APIs
publish-date=02142014