Externalized customizations (xC) programming model

To customize the IBM Commerce Service for your IBM Commerce on Cloud subscription, you must use the externalized customization (xC) programming model. The programming model provides you with a simplified process for creating custom extensions with REST services for your Commerce Service, and for customizing your store, search index, and search runtime.

The xC programming model enhances the Commerce Service command framework to enable remote extension customization of Commerce Service business logic, specifically controller commands, and task commands. With this enhancement, your customization logic is separated from IBM provided platform logic and code. This separation exists in your programming environment and in your IBM provided IBM Commerce on Cloud environments. To customize your Commerce Service, you need to focus on only the creation, function, and deployment of your custom code and extensions. You do not need to focus on the functionality of IBM provided platform logic, or on IBM provided upgrades to IBM provided logic.

To create the separation of your custom logic from IBM provided platform logic, a Customization server, Search server, and Store server are all added to each IBM Commerce on Cloud environment for your service. Your custom business logic runs on these separate servers, while the IBM provided platform code and logic continues to run on the WebSphere Commerce server. For customizing your Commerce Service, you must set up the these servers within your programming environment. Each server is used to customize different parts of a Commerce Service and to run different functionality.
  • All of your xC extensions that run on the Customization server. You must create and deploy any custom business logic on this server.
  • Your search index and runtime configuration runs on the Search server. You must complete and deploy any changes to the search index and runtime configuration on this server.
  • Your customized storefront runs on the Store server. You must complete and deploy any changes to your store front-end on this server.
  • All other Commerce Service components and functionality continue to run on the WebSphere Commerce server.
Important: As you are planning your customization, ensure that your design uses only extension points that are exposed as xC extension points by IBM to create your customization within the xC workspace. If you need to customize a component or function and an extension point is not available for customizing the component or function, open a request for enhancement and request that an extension point be made available that meets your requirements. For more information about the request for enhancement process, see IBM Commerce Service requests for enhancement (RFE).

The servers can use REST services to communicate and ensure that the extensions, customized assets, and functionality that run on each server operates successfully. For example, the WebSphere Commerce server calls xC extensions on your Customization server through REST services.


The xC programming model supports the most common Commerce Service customization scenarios. In addition, this programming model can provide you with the following benefits:
  • Greater control with managing and releasing your custom extensions and other changes. You can create deployable packages faster for deploying your custom changes. You can also deploy changes for each server independently. These changes allow you to schedule releases on a per server basis to reduce the size of your releases, which can help you better allocate your testing resources and potentially reduce the overall time that is required for you to deploy, test, and externalize your custom changes to your shoppers.
  • Simplified process for upgrading your service. The separation of your custom extensions and logic from the IBM provided logic and code removes dependencies between your code and IBM provided code, which simplifies the process for updating your service. This simplification allows for better support of seamless and continuous upgrades and deployments to your service. IBM provided upgrades, such as releases and fixes can be applied more efficiently to your environments, with reduced regression test requirements. For example, an upgrade can be deployed and applied to just the WebSphere Commerce server without impacting the operation of your extensions and without requiring changes to your custom logic and extensions.
  • Improved flexibility with assigning customization responsibilities. By developing your customization changes with this model, you can separate programming responsibilities among your developers and implementation Business Partner more easily. For example, a developer that needs to create a custom order xC extension can develop their changes within an Externalized Customization (xC) workspace that includes only the Customization server. The developer can then develop and deploy their changes independently of developers that are working on store and search configuration changes.

xC extensions

With the xC programming model, you can create business logic extensions. You can create these xC extensions for the following Commerce Service components:Extension points are provided for the following areas:

  • User registration extension points
  • Cart, order, and order integration extension points
  • Inventory integration extension points
  • Payment integration extension points
  • Tax integration extension points
  • Search extension points

An xC extension is a controller command or task command extension that is based on an IBM provided xC extension point, which is also known as a User Exit. All xC extensions must be based on only exposed xC extension points. For more information about these extension points, see xC extension point customization.

xC extensions represent customization logic for a specific customization requirement. The customization business logic that you create can have the following characteristics:
  • Your extensions can invoke custom implementations before or after default implementations run, and to replace default implementations. The custom implementations can trigger business object updates.
  • Your extensions can be for individual stores.
  • Your extensions can extend controller commands and task commands so that your code runs before or after the extended command, or as a replacement for the command.
  • Your extensions can be configured within the database, with no enterprise archive modifications required.
  • Your extensions can be created within your programming environment without redeploying or restarting the applicable server.
  • Your extensions can use any client library to make REST calls
  • Your extensions can use a JAX-RS client to call third-party REST services.
  • Your extensions can control the amount of data that is serialized.
  • Your extensions have no programming model-specific data objects that are used as request and response parameters.

After the extension is created, the extension must run on the Customization server for each IBM Commerce on Cloud environment as your customization logic can now run on separate servers from the IBM provided platform code and logic.

Store front-end customization

To customize your store front-end, such as to create or customize store JavaServer Pages (JSP files), widgets, and more, you must complete the customization on your Store server. You can customize these store assets by modifying, or adding and extending existing store files.

With this new programming model and with the Store server separated from the WebSphere Commerce Developer server, all of your custom store assets are now separated from IBM provided site-level store assets. IBM provided site-level store assets are included within a non-customizable store web archived. When you are creating your own custom store assets, you must include the assets within your own custom store web archive.

For more information, see Customizing the store.

Search index and runtime configuration

You can customize search for your site by changing your search configurations or adjusting the behavior of the WebSphere Commerce Search (Solr) engine. Changing these configurations require you to update configuration XML files on your Search server. For more information, see

Programming environment

To begin creating custom xC extensions that adhere to this programming model, you must create a programming environment that includes the necessary components. Your programming environment must include at least 2 workspaces, the WebSphere Commerce Developer workspace and at least one xC workspace. You must complete all customizations within your xC workspace, such as to create custom xC extensions and storefront customizations.

You can have a separate xC workspace for each type of xC server. You can have a separate xC workspace for the Store server, Search server, and the Customization server, which is used for creating xC extensions.

You can also include these workspaces within a single Rational Application Developer instance or on separate Rational Application Developer instances, such as on different development machines. To help you set up the servers and projects for an xC workspace, the SDK for IBM Commerce Service is available.

For more information about setting up these workspaces and the overall programming environment, see Setting up the Commerce Service programming environment.

Swagger API

As part of using this programming model to create your custom xC extensions, use the Swagger REST documentation. For every extension that you create, annotate the REST services that you use with JAX-RS annotations according to the Swagger 2.0 spec.
  • Swagger UI is available in the programming environment - http://host_name:9443/commerceue/swagger/index.html#!
  • Swagger spec JSON is available in the programming environment - http://host_name:9443/commerceue/extension/api/swagger.json