Cartridges

Business functionality in B2C Commerce is organized in cartridges.

Deploy and Iterate with the B2C Commerce CLI

Using the B2C Commerce CLI, deploy and manage cartridges directly from your terminal. To install the tool and authenticate, see B2C CLI, MCP and Tooling SDK.

1# Deploy all cartridges in the current project and activate the code version
2b2c code deploy --code-version version1 --reload
3
4# Deploy only specific cartridges
5b2c code deploy --code-version version1 --cartridge app_custom,int_payment
6
7# Activate a previously uploaded code version
8b2c code activate version1
9
10# Live-sync local file changes to the sandbox during development
11b2c code watch --code-version version1
12
13# List code versions on the instance
14b2c code list

For the full command reference, see Code Commands in the B2C DX documentation.

What Is a Cartridge?

A cartridge is a mechanism for packaging and deploying program code and data. Use cartridges to extend business functionality or integrate with external systems. A cartridge can deliver generic or application-specific functionality.

Generic cartridges: contain reusable business functionality that can be deployed to many sites.
Application-specific cartridges: designed to provide functionality that is specific to the needs of a particular ecommerce site.

Add a cartridge for functionality that is:

Generic: you want to reuse functionality among multiple projects.
Large and self-contained: you want the functionality self-contained for easier maintenance.

New functionality doesn’t always require a new cartridge.

Note

Cartridges can contain:

Controllers
Templates
Scripts
Form definitions
Static content (images, CSS files, and client-side JavaScript files)
WSDL files

You configure which cartridges are in use by entering a list of those cartridges in Business Manager. The order in which cartridges are listed matters. The list is basically a classpath, with the cartridge as the class. If you want to overwrite files with a particular cartridge, put the cartridge at the end of the list. Use the code upload version directories to change the active directory.

Cartridge Directory Using WebDAV

Download or view cartridges using a browser or a WebDAV client.

Use the following URL convention:

1https://<hostname>/on/demandware.servlet/webdav/<organization>/cartridges/<code version ID>

An example of <organization> is Sites, for example, https://ddd.ddd.dw.demandware.net/on/demandware.servlet/webdav/Sites/Cartridges

Note

If you want to use WebDAV to access cartridges, the name of the directory that contains the cartridges can contain no more than 50 characters.

Note

The currently selected code version is stored in this file:

1https://<hostname>/on/demandware.servlet/webdav/<organization>/Cartridges/.version

When using WebDAV to access your cartridges, you’re prompted to enter a username and password. Use your Business Manager username and password.

There are other WebDAV URLs for accessing catalog and content library assets. Click App Launcher and then select Administration > Site Development > Development Setup for WebDAV access via URL references.

Using WebDAV is one way to access a server-based file system to verify if the correct code has been uploaded. Another way is via the Business Manager.

Common problems include:

The server connection was disabled.
The server didn’t access your cartridge.

Download a Cartridge from an Instance

A best practice is to maintain cartridge code in a source control system available to developers. However, in rare cases, it’s useful to download a cartridge from a working instance.

Downloading the cartridge doesn’t download the related site data. To download that data, use Site Import or Export.

Click App Launcher and then select Administration > Site Development > Code Deployment.
Click the code version you want to download.

Usually you want to download the currently active code version, indicated by a green check mark in the Active column.
On the Version Summary page, click Download.

Register a Cartridge

After creating a cartridge, upload it to a server and register it to a site. Register a cartridge to multiple sites.

Click App Launcher and then select Administration > Sites > Manage Sites > site.
On the Settings tab, enter one or more cartridge names in Cartridges, separated by colons.

Cartridges take precedence in order from left to right.
Click Apply.