WebSphere Commerce best practices: Building an extensible and flexible WebSphere Commerce multi-store deployment

You can think of the organizational structure in WebSphere® Commerce as the skeleton that strings together business artifacts of the commerce system, such as catalogs and fulfillment centers. This structure plays a key role in determining business and functional privileges to these artifacts. This article describes how organizational structure decisions impact store assets, authorization, contracts, and LDAP integration.


Howard Borenstein (borenst@ca.ibm.com), Software Engineer, IBM Canada

Howard Borenstein is a software developer at the IBM Toronto Lab in Toronto, Ontario, Canada. He is the lead developer of the Business Relationship Management component of WebSphere Commerce. Howard has worked at IBM for 14 years, and has experience in user interface and Web application development, application development tools, and commerce applications. He has a Bachelor of Applied Science degree from the University of Toronto, Canada.

Ross McKegney (mailto:rmckegne@cas.ibm.com), Software Engineer, IBM Toronto Lab

Ross McKegney is a staff software developer at the IBM Toronto Lab, Ontario, Canada. He currently builds software components and infrastructure to support multi-channel retail solutions. Previously, he was the architect and development lead for the member subsystem in WebSphere Commerce. Ross has a MSc degree in Computer Science from Queen's University, Canada.

Darshanand Khusial (dkhusial@ca.ibm.com), Security Architect, IBM

Darshanand Khusial is the lead architect for WebSphere Commerce in IBM Software Group at the IBM Toronto Lab, Ontario, Canada. He has a Master of Engineering degree from the University of Toronto, Canada.

17 May 2006


There are a number of interrelated considerations when defining a multi-store WebSphere Commerce deployment. The WebSphere Commerce platform allows for many assets to be shared across stores, and choosing an appropriate layout allows for the best leveraging of these reusable assets. This article uses a case study approach to illustrate typical considerations made when designing a multi-store deployment. It focuses on store layout using asset stores, roles, policy groups, contracts, and buyer and seller organizational structures.

Case study: Custom model for TiresAmericas

TiresAmericas has a small number of brick and mortar franchise stores in North America and Latin America. To give their business more visibility worldwide, they have decided to launch an online presence, initially targeting the countries where they currently have stores. These countries are USA, Canada, and Chile. In the near future, they anticipate expanding to other Latin American countries, but they want to start with an online presence in these countries. After seeing the demonstration of the sample business models that shipped with WebSphere Commerce V5.6.x, they are convinced that this product has all the features they need.

Below are TiresAmericas' requirements for store layout, catalog setup, and authorization:

  • To better target the different cultural preferences of their customers, they use a Mexican Web design firm to build the pages for their Spanish store, while an American Web design firm is used to build the English stores. Their analysis has shown that North American customers and Latin American customers have different spending habits. For example, North American customers pay a premium for brand names, whereas Latin American customers do not. As a result, TiresAmericas wants to convey a different user experience to these two groups.
  • Although many of the store pages are shared among all stores within a cultural region, some pages need to be unique on a per-store basis, such as the store homepage.
  • The store catalog is shared among all three stores, and they anticipate keeping it this way. However, the Latin American stores do not sell winter tires. Similarly, individual country stores may not sell certain categories or products.
  • There is a master price list for TiresAmericas product line. However, category and product discounts may be set for a region, an individual country, and individual customers.
  • Only registered users are allowed to shop the Chile store. In the other stores, both guest and registered users are allowed to shop.
  • TiresAmericas sells to customers directly and to auto shops for offline resale to customers. These auto shops are entitled to special reseller pricing.

The following sections outline some of the capabilities within WebSphere Commerce 5.6 that address these requirements. They also cover best practices.

Given the interrelationship between organizations, stores, authorization, and contracts, it is recommended that you design these parts iteratively. First determine how many stores you need to deploy either immediately or in the future, lay these out on an organization structure following the guidelines in store section. Scope out the authorization to these stores, rearranging the organization structure as necessary as per the guidelines in the authorization section below. Next, determine the contracts that need to be established for the various stores and tweak your organization layout as appropriate using the recommendations in Organizing contracts to enforce business rules. Finally, repeat this process to ensure that the changes you made at each step did not result in an undesired organizational layout.

Arranging stores to segregate content

You can use a WebSphere Commerce store anytime you want to provide a different configuration or experience for a group of customers. You may have a separate store for each of your brands, for different geographical regions, or in some cases, to provide a customized shopping experience for each of your large customers.

There are two types of stores: customer-facing stores and asset stores. A customer-facing store is one that customers can access directly. An asset store shares its resources to other stores. A customer-facing store may contain all its artifacts or leverage some from an asset store.

The WebSphere Commerce infrastructure is designed in such a way that a vast majority of the content required by a store can be reused, but it also allows establishing points of variation to support unique requirements. For example, stores for different geographical regions may sell different assortments. However, there is no need to redefine product Store Keeping Units (SKUs) when the assortments overlap. Instead, the concept of a shared master catalog is provided, and each store filters the master catalog to provide their assortment. Shared assets such as catalogs, contracts, and even display artifacts like JSPs, can be shared between stores by leveraging the concept of an asset store, effectively a container store.

Each store is owned by an organization in the organizational hierarchy. The fundamental reason is that this ties the store in with the WebSphere Commerce access control model. When a user plays a role at the store owning organization (or one of its ancestors), then the user plays the role for the store. For example, if a user plays the Customer Service Representative at the store, then they are allowed to logon to the tooling under the context of this store, and view any users/transactions for this store. When deciding on a store layout, it is important to consider the number and nature of the stores to support (including asset stores), and the organizational structure that will be put in place to contain them.

As described above, TiresAmericas plans to deploy three distinct storefronts in two languages. They anticipate expansion in the future, and want to reuse as much of their storefront content as possible. Based on these considerations, TiresAmericas has decided to deploy three B2B stores arranged hierarchically by region, leveraging asset stores for the shared catalog content and for each of the presentation languages supported. These assets are shown in Figure 1.

Figure 1. WebSphere Commerce assets for seller-side of TiresAmericas site
WebSphere Commerce assets for seller-side of the TiresAmericas site

Each of the three TiresAmericas customer-facing stores is created under the "Tire Retailers" organization. These three stores also share the same catalog, although each store establishes contracts to filter the catalog to only the products that are sold from that store. The locale specific JSPs used for content display are stored in the two asset stores, the Spanish Asset store and the English Asset store. They are used by the Chile and USA/Canada stores, respectively.

All the categories and products available on the site are defined in one catalog asset store. The customer-facing store only needs to define a "catalog" store relationship to the catalog asset store to share its resources. A contract in the customer-facing store allows you to further modify what is sold in the store, and at what price.

Best practice: Keep organizations for stores, asset stores, and buyers in distinct branches of the tree. Because the organizational structure is such a fundamental aspect of the site's architecture, organizations should never be moved or deleted. Therefore, coupling between stores and their customer organizations, for example, should be done through roles and contracts rather than through the organizational hierarchy.

Best practice: Create stores at leaf nodes in the organizational hierarchy. This puts each store on a unique branch of the tree. The rationale for this best practice is that, if two stores are on the same branch, it now becomes impossible to assign a role to a user in the higher store without them inheriting the role in the lower store as well. If two stores are logically related (as in our example above, where the stores were related by region), then introduce an intermediate node, but keep the stores as leaf nodes.

Laying out roles and policy groups to control authority


The authorization model of a WebSphere Commerce application has three primary concepts: users, actions, and resources. Users are the people that use the system. Resources are the entities that are maintained in or by the application. Actions are the activities that users can perform on the resources. Access control is the component of the e-commerce application that determines whether a given user can perform a given action on a given resource.

The WebSphere Commerce access control framework uses access control policies to determine if a given user is allowed to perform a given action on a given resource. WebSphere Commerce access control policies are 4-tuples with the following form:

AccessControlPolicy [UserGroup, ActionGroup, ResourceGroup, Relationship]

The elements in the 4-tuples access control policy specify that a user belonging to a specific user group is allowed to perform actions in the specified action group on resources belonging to the specified resource group, as long as the user satisfies the conditions specified in the relationship or relationship group.

Most conditions to include a user in a user group are based upon the user fulfilling a particular role. For example, there is an access control policy that allows all users that fulfill the Customer Service Representative role to perform customer management operations. Any user that has been assigned the Customer Service Manager role in the MBRROLE table is then implicitly included in the user group.

Users play roles in organizations. You can design access control policies to grant authority to a user based on their role in a particular organization. Additionally, you can design policies to respect roles on the store's ancestral organizational branch. If you are accessing a resource in a store and the policy for that resource dictates that the user must have the Registered Customer role, you can design the policy to respect any Registered Customer role on the organization ancestral branch.

TiresAmericas sells directly to customers in all three stores. Upon registration, B2C shoppers are created in the Default Organization, and are granted a Registered Customer role that allows them to shop at one or more stores.

Figure 2. B2C shoppers
B2C shoppers

Although all three stores are published to the same site, shoppers are registered to only one of the stores by using the store-level registration feature, which is a feature of WebSphere Commerce since version 5.5. When a shopper registers to one of the three stores, they are given the Registered Customer role in that store only. If the same customer wants to shop at more than one of the stores, they have to create a new user profile for each store. In this way, each store can act autonomously. See Store Level Registration in WebSphere Commerce 5.5 for more details on store level registration.

Best practice: Although you can create all three stores under a single organization, there are benefits to defining a hierarchical organization structure that matches your business requirements. In this instance, we have recognized that it may be desirable to have a single shopper registered to both the Canada and USA stores (but not the Chile store). Similarly, on the administration side, it may be desirable to grant an administrator rights to all stores within a region.

Best practice: Avoid assigning non-administrative roles, such as the Registered Customer role, to the root node. Assigning users a role, such as the Registered Customer role, to the Root Organization grants them the ability to shop at any store on the site. This limits your ability to segregate customer's access to stores based on reasons such as branding or geography.

Policy groups

Since WebSphere Commerce 5.5, the access control infrastructure has been enhanced with the policy group subscription feature. Policies are grouped into policy groups based on business and access control requirements. For example, one policy group has policies needed to support contracts, while another allows only registered users to shop. Depending on an organization's business and access control requirements, the organization explicitly subscribes to the appropriate policy groups. When an organization subscribes to policy groups, only the policies in those policy groups apply to the organization's resources. Its ancestor organizations' policies do not apply. However, if an organization does not explicitly subscribe to policy groups, it inherits the policy subscription of its closest ancestor that is subscribing to policy groups.

Figure 3. Policy group subscription for TiresAmericas stores
Policy group subscription for TiresAmericas stores

Figure 3 shows the available policy groups in the system. These are illustrated as cylinders that have a label at the top. The four policy groups shown are owned by the "Root Organization" via the arrows. They are bootstrapped into the system when you create a WebSphere Commerce instance. A brief description of each follows:

  • B2C Policy Group: This group contains policies for the preloaded WebSphere Commerce commands that are not in the Common Shopping Policy Group. These policies apply only to a consumer direct store, such as defining and allowing guests to shop.
  • B2B Policy Group: This group contains policies for the preloaded WebSphere Commerce commands that are not in the Common Shopping Policy Group. These policies apply only to a Business Direct store, such as defining and allowing for the execution of contract commands. The policies in this group only allow these commands to be executed by registered customers.
  • Management Policy Group: This allows administrators to manage the stores.
  • Common Shopping Policy Group: This allows execution of preloaded WebSphere Commerce commands. These commands are catalog, order, and payment commands that are common to both a consumer direct and business direct stores. The policies in this group only allow these commands to be executed by registered customers.

There are two other policy groups that are shown in the system. These groups contain policies for resources of the asset stores when you cannot use an existing policy from those bootstrapped in the system. These two groups are created during construction of the asset stores. As an example, if you add a new command in your Spanish asset store called SpanishCategoryDisplay, you need to create the Spanish policy group and add the policy to allow access to this new command. In Figure 6, there is one policy group for the English asset store called the "English policy group", and another one for the Spanish asset store called the "Spanish policy group".

Figure 3 shows subscription to policy groups by placing the label of the appropriate policy groups near the organization where it applies. Below we describe how the authorization requirements that we laid out earlier in our case study are achieved. You cannot shop the asset stores. You achieve this by inheriting the Management Policy Group that is subscribed to at the "root organization".

For the English stores, you achieve guest and registered shopping by subscribing to the four bootstrapped policy groups described above and to the English policy group. Notice that you had to re-subscribe to the Management Policy Group because as soon as an organization subscribes to a policy group, it does not inherit any of those from its ancestors.

For the Chile store, you achieve only registered customer shopping by subscribing three bootstrapped policy group and ignoring the B2C Policy Group that allows guest shopping. You also subscribe to the Spanish policy group to execution of the resources that you use from the Spanish asset store.

Best practice: Create a unique policy group for each asset store in your deployment. Doing this would make it easy to setup access to a customer-facing store that have a storepath to an asset store as all that is required is for the presentation customer-facing store's to subscribe to the corresponding policy group of the asset store it leverages.

Organizing contracts to enforce business rules

We will use contracts to satisfy the requirement for contract-based pricing. Before we get into the details, let's step back and look at the contract model to get an understanding of the business objects involved.

A contract defines the terms and conditions under which a customer shops while they are in a commerce site. These terms modify the customer's shopping experience, including what products the customer can purchase, what prices they are entitled to, and what shipping and payment options they may use. To enable a contract to be accessed by customers in a store, the contract is deployed to the store.

There are two types of contracts: customer contracts and base contracts. A customer contract has an organization and buyer participant. All members of the organization are entitled to purchase using the contract.

Base contracts are used to contain sets of terms and conditions that can be shared by many customers. No customer is directly entitled to a base contract. A customer is allowed to use the terms and conditions from a base contract only if one of their customer contracts refers to the base contract. Using base contracts allows for more efficient use of data within the commerce system, and requires less management effort. The base contracts can contain any contract terms and conditions, but usually have the Catalog Filter term and condition that defines which products are for sale and at what price. A customer is entitled to purchase the products specified by the terms and conditions in their customer contract, along with all the terms and conditions specified by the base contracts referred to by the customer contract. Similarly, the customer will get the best price as defined by the terms in the customer and base contracts.

Both customer contracts and base contracts are held within a business account. A business account is associated with one organization. For customer contracts, the organization is the buyer's top level organization and the business account contains terms and conditions that apply to all the buyer's contracts. For base contracts, the organization is only a holding organization with no buyers. The business account allows related base contracts to be grouped together, and does not contain any terms and conditions.

To manage base contracts in the WebSphere Commerce Accelerator, you create a base contracts organization and an associated account. Customers will not be associated with this base contract organization. The base contracts account is just used as an entry point to manage the base contracts, and this keeps the contract model consistent between base and customer contracts (organizations are associated with a business account, and accounts have contracts). It is recommended that each level in the contract hierarchy have an associated base contracts organization and account. This will allow the base contracts in one level in the hierarchy to refer to contracts in a different level.

When an extended site is created using the Store Creation Wizard, a base contracts account is created for the store, and the account contains a base contract. This base contract is called "Storename Base for Default Contract". This contract contains the pricing and product terms and condition applicable for the store. The store's default contract refers to the "Storename Base for Default Contract". This allows you to apply any terms that apply to all customers within the store, including guest shoppers, in one contract. For example, if your store does not sell some categories from the shared catalog, they can be excluded in the base for default contract. You can set any pricing that applies to all customers in this contract. All contracts in the store directly, or indirectly, refer to the base for default contract.

Figure 4. USA Store contract model
USA Store contract model

Figure 4 illustrates an example of the contract model for the USA store. B2B customers will each have their own business account within the store. When creating contracts for these customers, the contracts refer to the Base for Default Contract to share the terms that are applicable to all customers. Guest customers in the store are entitled to shop under the USA Store Default Contract, which also refers to the base for default contract to share the terms that are applicable to all customers. The USA Store Base for Default Contract will contain the Catalog Filter term and condition that can exclude for sale any products from the master catalog, and offer any preferred pricing on categories and products applicable to the entire USA store. Each customer's contract will also contain a Catalog Filter term and condition that can further exclude for sale any products, and offer any preferred pricing on categories and products applicable to the customer.

Figure 5. TiresAmericas contract model
TiresAmericas contract model

For TiresAmerica, pricing and product entitlement are specified at the corporation and regional level. To support this, the base contracts contain the corporation and regional terms, and these base contracts are shared across multiple stores. To share contracts across stores, create them in a shared asset store as shown in Figure 5. Usually, the shared asset store would be a storefront asset store. However, for TiresAmerica, there are two storefront asset stores, so create a contract asset store to manage all the base contracts in one location. This allows the contracts to be shared in any extended site store that has the "com.ibm.commerce.contract" storepath relationship with the contract asset store.

For each level in the base contract hierarchy, a corresponding base contract organization and business account are created. The business account will contain the applicable base contracts for that level. The Common account will have a base contract that has the pricing and product terms applicable to the entire corporation. The Region account will contain a base contract for North America and Latin America, and both will refer to the common base contract. In turn, the Base for Default Contract in each country store will refer to the appropriate regional base contract. Thus for a shopper, they are entitled to the terms and conditions from their customer contract or store default contract, the country Base for Default Contract, a regional contract, and the common corporation contract.

For TiresAmerica, winter tires are not sold in Latin America, so the Latin America base contract will exclude the Winter Tires category in the Catalog Filter.

Let us consider a customer who belongs to the SunnyTire organization and they are shopping in the Chile store. Members of the Sunny Tire organization are entitled to shop using one contract, the SunnyTire contract. However, the terms and conditions applicable to the Sunny Tire contract will be a combination of the terms from the SunnyTire contract, the Chile Base for Default Contract, the Latin America Base Contract, and the Common Products and Pricing Base Contract. The Latin America Base Contract excludes Winter Tires from being sold. An exclusion term will take precedence over any inclusion terms, so the customer cannot purchase Winter Tires. The customer wants to buy an all season tire with SKU abc-123. The price offered for the tire is the best price as defined by the customer contract and the three base contracts.

To create a base contract account using the Commerce Accelerator, you must identify the base contract organization as a business entity (an organizational entity that can have a business account). If the store has a RegisteredCustomers member group, then the base contract organization must be a member of the group. If the store does not have a RegisteredCustomers member group, then the base contracts organization must have the BusinessEntity member attribute flag. Any organizations created using the Organization Administration Console, and whose parent organization is the Root Organization, is assigned the business entity flag. Alternatively, you can modify the <BusinessEntities> element in MemberRegistrationAttributes.xml to assign the BusinessEntity flag to other organizations based on their parent organization. When creating the business account, select the "This account is to be used for base contracts" checkbox.

Figure 6. B2B buyers
B2B buyers

OrganizationSetInSession sets the active organization in the session. Previously, a user could only have one active account (their parent organization). In many instances, the user may be entitled to shop on behalf of multiple organizations. The ability to define the organization to shop for has been added as part of session management. Depending on the active organization, the valid set of contracts (and therefore catalog filtering and pricing) will be based on that active organization. ContractSetInSession restricts the contracts a user can use by only allowing a subset of the customer's entitled contracts to be used in the customer's session. Both of these features support a site's requirements, and the design of an appropriate contract model. However, the details of these features are beyond the scope of this article.

Best practice: Our example illustrates the importance of taking the time to fully understand the product and pricing requirements for the site. Understanding these requirements lead to creating the appropriate contract hierarchy of shared base contracts and customer contracts. Place common terms and conditions in base contracts. If these terms are shareable across stores, then place the base contracts in an asset store.

LDAP/SSO considerations

Organizations in WebSphere Commerce are used to define the skeleton of the site, as containers for stores, asset stores, buyers, and sellers. An important consideration when laying out the organizational structure is whether or not LDAP integration is desired. WebSphere Commerce supports LDAP as the master repository for customer authentication and profile information, and is a prerequisite to leveraging the Single Sign-on capability with other WebSphere applications that is also provided out of the box. The implication of LDAP now being the master repository for user and organizational data is that the organizational structure defined in WebSphere Commerce must exist on your LDAP server. This often means reconciling an existing LDAP organizational tree with the desired WebSphere Commerce layout, and adding new branches for the WebSphere Commerce specific resources. If LDAP integration is something that is desired for your site, the desired LDAP structure should be considered at the time when the WebSphere Commerce organizational structure is being devised. Detailed information on LDAP integration is provided in the WebSphere Commerce online help.

Figure 7 presents the organizational structure that result for TiresAmericas. If LDAP integration was desired, then each of these organizations would need to exist in the LDAP server (pre-populated, or created dynamically by WebSphere Commerce).

Figure 7. Final organizational layout
Final organizational layout


The organizational structure in WebSphere Commerce is a cross-cutting concern, affecting many of the decisions made at design time for your site. This article described key considerations when laying out your site, including a number of best practices that enable an effective multi-store deployment. The article also outlined the concepts of stores, contracts, policy groups, and LDAP. A case study illustrated how these concepts interrelate, using concrete examples of best practice implementations.





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 WebSphere on developerWorks

ArticleTitle=WebSphere Commerce best practices: Building an extensible and flexible WebSphere Commerce multi-store deployment