Code Deployment

You can manage code versions and securely upload code.

B2C Commerce lets you have multiple custom code versions uploaded to the system at the same time. The code is arranged in a top-level directory, called Version Directories. You can name each directory in accordance with your versions, for example, v12 or summer_release.

When developing your storefront, select one active code version with which to work by going to Administration > Site Development > Code Deployment. Select a version directory as the active version for a site. All templates, pipelines, scripts, and images are taken from this active version.

B2C Commerce automatically and asynchronously removes the oldest code versions on all instance types. The active code version and the previously active code version are not included in this process. You can configure the number of retained code versions.

You can roll back your storefront to a previous version if necessary. Develop your application with a newer version while maintaining an active storefront on a stable code base.

B2C Commerce doesn't let you upload code using a .zip file containing a distinct code version. Instead, you must upload your cartridge. Most development teams have a regular method for uploading code to staging.

If you get the following error when you try to view the storefront, check that you are uploading your cartridge to the current code version.

Best practice is to upload code into an inactive version on a Staging instance and later replicate the code to a Development or Production instance.

Code uploads into an active version are only allowed on Staging, Development, and Sandbox instances. Production instances reject WebDAV based code uploads that occur directly into the currently active version. Code uploads onto a Production instance can only be to an inactive version.

You can also specify the active compatibility mode (API version). B2C Commerce lets you activate a new compatibility mode or revert to the previously active compatibility mode.

You can replicate code to another system. Code Replication transports the active code version from the staging instance to the target production or development instance.

A code version is a folder that contains custom cartridges. An instance uses the currently active code version. You can upload additional code versions to the server via WebDAV. These can be new code versions that will be activated later, or previous ones to allow for code rollbacks.

A compatibility mode can be assigned to each code version and is activated when the code version is activated. Code versions that have not been explicitly assigned to a compatibility mode are marked with an asterisk (*) and assume the current active compatibility mode. Selectable compatibility modes are those that are newer than the active compatibility mode, in addition to the previously active compatibility mode. You can't select a compatibility mode that is older than the previously active one.

The platform automatically and asynchronously removes the oldest code versions on all instance types. The active code version and the previously active code version are not included in this process. You can configure the number of retained code versions (see below).

1. Select Administration > Sites > Manage Sites. You must assign custom cartridges to sites.

2. Select Administration > Site Development > Code Deployment.

   On the Manage Code Versions page, there are two timestamp columns:

   • Modification time: Ddate and time the code was created or last updated on the instance.

   • Activation time: Date and time of the last code activation.

     The timestamp changes after an activation, roll back (for the new active version), or replication. Code versions that were not activated don't show an activation time, for example, a new code version.

     If you upload code changes without creating a new cartridge, activation time represents the date and time the code initially went live on a Production instance.

3. Click a link in the Code Version column.

   The Version Summary page opens, where you can drill down into the code via WebDAV.

4. Click a compatibility mode link to view a list of available compatibility modes.

   The Compatibility Mode page opens with a list of available compatibility modes.

   • The currently active compatibility mode
   • The previously active compatibility mode
   • Any new compatibility modes that you can select Each compatibility mode provides a Change Docs link that provides a summary of applicable changes and a Documentation link to the respective API documentation.

5. Click Back to return to the Manage Code Versions page.

6. To rename a code version, click Rename beside a code version in the list.

   Renaming a code version also changes the respective entries in the version file.

7. To activate a code version, click Activate beside a code version in the list.

   It isn't possible to select a compatibility mode older than the previously active one.

   A code version is activated by adding its folder to the list of folders in which the server looks up resources. At the same time, the folder of the previous active code version is removed from the list.

   The features included in the new code version are immediately available. Cached items (which might be dependent on a change to the compatibility mode) are cleared after activating a new code version.

8. Click Rollback to automatically activate the previous code version, if this code version is still installed.

   If the previous code version is no longer available (it has been deleted), the rollback fails. The action also activates the compatibility mode associated with the previous code version.

9. Select one or more inactive code versions and click Delete to delete them. You can't delete the active code version.

10. Click Add to create a new empty code version. The new code version will be set to the currently active compatibility mode.

    To protect B2C Commerce against directory traversal attempts when creating or renaming a custom code version, an exception is thrown on any attempts to access a parent directory or sub-directory. For example, you can't pass my/new/version when creating or renaming a custom code version. The effective version name is the end of the expression, in this case, version. This type of input results in an error.

11. To configure the number of retained code versions:

    1. Select Administration > Site Development > Code Deployment (admin user only).

    2. In the Code Version Retention section, enter the number of retained code versions (3 to 20, the default is 10).

       The initial value for existing customers is 0, which means that the feature is disabled. If you activate this feature (by setting a value other than 0) only Salesforce Support can reset it to 0. All newly provisioned instances have a default of 10.

    3. Click Apply.

12. To work with a single version:

    1. Click the code version name link.

       The Code Version Summary page opens.

       This page provides a detailed view of the code version. The top section provides summary information, while the bottom section provides a paged list view of resources that are part of the code version. The list view shows files regardless of where they are located within the code version (that is, regardless of cartridge and subdirectory).

    2. Click Activate to activate this code version.

    3. Click Download in the top section to download the entire code version, or click Download beside an individual file to download that file.

    4. Use the File Filter to search for a file or set of files.

As a best practice, maintain consistent use of version numbers for each software update.

It is tempting to simply upload a fix to a current production directory. But if there are problems, this approach doesn't permit quick roll backs. This approach can also cause unnecessary delays in addressing a potentially critical situation.

Using version numbers consistently helps development and support teams diagnose and fix issues in a timely manner. If a new version causes issues that were unknown during the test phase, support can roll back to a previous known working version. Being able to roll back is especially helpful if a version makes the system unstable and support is required to respond in a 24x7 environment. With versioning, the development team can review specific code fixes within the context of multiple previous versions.

Compatibility mode refers to a B2C Commerce API version that includes changes that affect backward compatibility with the previous API version.

Not every API version affects backward compatibility, so only some API versions have a compatibility mode. API versioning enables you to actively select from multiple compatibility modes, with the full knowledge and acceptance of incompatible changes. The ability to select the compatibility mode you want to use enables you to maintain your customizations on a previous compatibility mode, while B2C Commerce introduces new functionality in one or more newer compatibility modes.

Selectable compatibility modes are newer than the active compatibility mode, in addition to the previously active compatibility mode. You can't select a compatibility mode that is older than the previously active one.

B2C Commerce supports a single active compatibility mode; and maintains a reference to the previously active compatibility mode, to which you can revert, if necessary.

The complete list of compatibility modes available at any time consists of:

• The currently active compatibility mode
• The previously active compatibility mode
• Any new compatibility modes you can activate

When your system was initially provisioned, the active compatibility mode was set to the latest (or most recent) compatibility mode. For example, if you initially provisioned with version 2.10.6, then the active compatibility mode is 2.10.6 because 2.10.6 introduced a corresponding 2.10.6 API version (compatibility mode).

You can specify how many code versions to retain. The oldest, except for the active and previously active code versions, are automatically removed by B2C Commerce (Sandboxes only).

A single API documentation set describes multiple compatibility modes at the class and method level, and potentially multiple compatibility modes for certain methods.

Before activating a new compatibility mode, it's important that you understand the behavioral changes the new mode brings. If the change impacts your application, you might need to modify your application to make it function correctly with the changes and then test. You can only roll back to the previously active compatibility mode if your code is compatible with the old mode (API version). If you write code that takes advantage of the API of a newer version that is incompatible with the old version, you can only roll back if you also revert the respective code.

When using API versioning, you must pay close attention to certain situations:

• All cartridges in an application must use the same active compatibility mode.
• There can be only one active compatibility mode at a time (no wildcard support).
• You can change the compatibility mode on all instances, but we don't recommend that you change the mode directly on Production.
• Avoid using different compatibility modes on Staging and Production.

To upload code securely, use two-factor authentication to upload the code to the staging instance. After the code is on the staging instance, use code replication to propagate the code from staging to the production instance.

For a human user, use a Business Manager or Account Manager username and password as the first factor for uploading to staging. For an automated script, use Account Manager to get an authorization token for a Client ID and use that as the first factor. See OCAPI OAuth 2.0 for details about authenticating an API client. The second factor of authentication for code uploads to staging is always a client certificate. To enforce this process of secure uploads, make sure that your configuration requires two-factor authentication for uploading code to the staging instance, and disallows code uploads to the production instance. As of August 1, 2020, Salesforce mandates these settings.

1. See if two-factor authentication is required for uploading code to your staging instance and enable if necessary:

   1. Log in to Business Manager on the staging instance as a user with administrative privileges.

   2. Go to Administration > Site Development > Development Setup.

   3. Look at the status message under WebDAV Access, Cartridges.

      If the message is A client certificate is required to upload code to this instance type, two-factor authentication is already enabled. If the message is A client certificate isn't required to upload code to this instance, two factor-authentication isn’t enabled and you must enable it, as described in the next step.

   4. To enable two-factor authentication, go to Administration > Global Preferences > Security > Access Restriction and select Require client certificate for code uploads.

      When you require the client certificate for code uploads, the option to configure this setting is no longer available in Business Manager. Only Salesforce Customer Support can revert the setting.

2. See if code uploads are allowed to your production instance and disallow if necessary:

   1. Log in to Business Manager on the production instance as a user with administrative privileges.

   2. Go to Administration > Site Development > Development Setup.

   3. Look at the status message under WebDAV Access, Cartridges.

      If the message is Uploading code to this instance type isn't allowed, code uploads are disallowed to the production instance. If the message is Uploading code to this instance type is allowed, code uploads are allowed to production and you must disallow uploads, as described in the next step.

   4. To disallow code uploads, go to Administration > Global Preferences > Security > Access Restriction and select Disallow code uploads.

      When you disallow code uploads, the option to configure this setting is no longer available in Business Manager. Only Salesforce Customer Support can revert the setting.

Use Business Manager to replicate code from Staging to Production.

1. Ensure you have the current updated version of the API on which the instance is running.

   1. Ensure that deprecated APIs are accounted for in your application. (Check the WebDav/Sites/Logs/deprecation/ directory on your server for a full list of deprecated APIs in use.) This ensures that references to deprecated APIs are removed before the API is discontinued.

   2. Ensure that any sandbox used for site development is upgraded at the same time as the Primary instances.

2. Merge code in the code repository.

3. Retrieve the collective changes from the code repository, then deploy the code to a Build/Merge instance.

4. Use Business Manager to create a new B2C Commerce version directory on the Staging and Development instances.

   1. Select Administration > Site Development > Code Deployment.

   2. Select an active version for these instances.

5. Provide a readme.txt file in the cartridge that lists the code fixes/enhancements in this version.

6. Copy the cartridge to the newly created version directories on Staging and Development via WebDav.

7. Test the new version (see above consideration).

8. Push the newly tested version to the Production instance for live usage. Use Business Manager to push code from Staging to Production. Click Administration > Replication > Code Replication. The replication process takes the current active version directory, creates the same version directory, then copies the cartridge code from Staging to Production.

Two-factor authentication to upload code securely to the staging instance requires a username and password or authentication token as one factor and a client certificate as the second factor. Generate the client certificate and sign it with a key provided by Salesforce. You can generate multiple client certificates with different expiration dates.

You must have a B2C Commerce Certificate.zip file to complete this procedure. Salesforce typically provides the Certificate.zip file as part of the realm provisioning request. You can also request a Certificate.zip file from Salesforce Customer Support.

The Certificate.zip file contains the following files:

• {\<name>}.key
• {\<name>}.crt
• {\<name>}.srl
• {\<name>}.txt

<name> is a unique identifier that reflects your instance or company name, plus a serial number. For {\<name>}.srl only, the serial number is not included in the file name.

The {\<name>}.txt file contains the passphrase used to access the key. You must provide this passphrase every time you sign a key request.

The files in Certificate.zip are highly sensitive. A best practice is to provide the files to only a single trusted employee within your organization, typically the administrator of your B2C Commerce instances.

1. If you are using Windows, install OpenSSL on your machine.

   If you are using MacOS or Unix operating system, you don't have to install OpenSSL. OpenSSL is provided as part of the operating system.

   1. Download a Windows OpenSSL client from the following location: http://www.slproweb.com/products/Win32OpenSSL.html

   2. Accept the default installation instructions. OpenSSL is installed to C:\OpenSSL.

      These instructions assume the default installation location.

2. Create a certificate request.

   1. Unzip the Certificate.zip file.

      If you are using Windows, unzip the contents of the file to the C:\OpenSSL\bin directory. If you are using MacOS or a Unix operating system, use any directory of your choice.

   2. Navigate to the directory where you unzipped the contents of Certificate.zip.

   3. To generate a request, enter the following command: openssl req -new -sha256 -newkey rsa:2048 -nodes -out {\<user>}.req -keyout {\<user>}.key

      Salesforce B2C Commerce doesn't support client certificates with key length less than 1024 bits. We recommend that you use client certificates with at least a 2048-bit length. <user> is the user that this key is for. We recommend that <user> be the same as the corresponding Business Manager user. For example, if the B2C Commerce instance username is jsmith, use jsmith for the certificate user. Don't use a generic name like Release Team.

      The result of this step is similar to the following:

   4. When prompted, provide your location and name information and the email address of the person using the certificate.

      We recommend that you leave the challenge password and optional company name blank. The challenge password isn't used.

      For example:

   OpenSSL creates files named {\<user>}.req and {\<user>}.key, in the same directory where the contents of the Certificate.zip file are stored.

3. Sign the certificate request ({\<user>}.req) with your certificate.

   1. Enter the following command at the command prompt: openssl x509 -CA {\<name>}.crt -CAkey {\<name>}.key -CAserial {\<name>}.srl -req -in {\<user>}.req -out {\<user>}.pem -days {\<days>}

      • <days> is the number of days you want this client certificate to be valid.
      • <name> is the unique identifier provided by Salesforce, as reflected in the file names in the Certificate.zip file.
      • <user> is the user of the client certificate you are signing. For example:

      openssl x509 -CA cert.staging.web.customer.demandware.net_01.crt -CAkey cert.staging.web.customer.demandware.net_01.key -CAserial cert.staging.web.customer.demandware.net.srl -req -in jsmith.req -out jsmith.pem -days 10

      The result of this step is similar to the following:

   2. Enter the passphrase contained in {\<name>}.txt in the Certificate.zip file to sign the certificate.

4. Export the certificate and client information to pkcs12 format.

   1. Enter the following command: openssl pkcs12 -export -in {\<user>}.pem -inkey {\<user>}.key -certfile {\<name>}.crt -name "{\<user>}" -out {\<user>}.p12

      • <name> is the unique identifier provided by Salesforce.
      • <user> is the user of the client certificate you are signing. For example:

      openssl pkcs12 -export -in jsmith.pem -inkey jsmith.key -certfile cert.staging.web.customer.demandware.net_01.crt -name "jsmith" -out jsmith.p12

      The system prompts for an export password for the file.

   2. Specify an export password.

      Provide the export password to the person who uses the certificate.

      The system creates files named {\<user>}.pem and {\<user>}.p12 in the same directory where the contents of the Certificate.zip file are stored. You can use the {\<user>}.p12 file to connect to a staging instance with UX Studio, as described in the next step. You can also use other WebDAV clients such as the Windows built-in WebDAV client, or third-party tools such as Cyberduck.

5. To connect to a staging instance with UX Studio, create a server connection.

   1. Open UX Studio and click File > New > Digital Server Connection.

   2. Enter the new instance URL as cert.staging.{\<realm>}.{\<customer>}.demandware.net.

   3. Click the Use Certificate Authentication check box.

   4. Browse to the {\<user>}.p12 file and click Select.

   5. Enter the export password for the {\<user>}.p12 file.

   6. Click Finish.

      If there is a proxy server between UX Studio and your instance, test your connection. If you can't connect to your staging instance, install the certificate on the proxy server. See your proxy server documentation for more information on uploading certificates.

   7. If you have to extract the certificate from the pkcs12 file before uploading it to the proxy server, enter openssl pkcs12 -in {\<user>}.p12 -clcerts -out {\<user>}.cer

      • <user> is the user of the client certificate. For example:

      OpenSSL prompts you for the password on the pks12 file.

The Salesforce B2C Commerce architecture lets you create multiple Sandbox instances where individual developers can work on discrete portions of an application, making efficient use of resources. At release time, developers file their changes back into a source control system for consolidation and testing.

Eclipse comes with a built-in client for the Concurrent Versions System (CVS). You can also use another system, such as Subversion (SVN) for your code repository. Many code repository/version control systems use a branch model to support multiple courses of work that are somewhat isolated from each other, yet still highly interdependent. This model lets individuals work on a team project, share their work with others as changes are made, and access the work of others as the project evolves. As team members produce new work, they share their work by committing their changes to the branch. Similarly, when they want to get the latest available work, they update their local workspaces to the changes on the branch. Thus the branch is constantly changing, moving forward as team members submit new work.

As a B2C Commerce development team member, it is important that you implement both a code repository/version control system and a versioning plan that follows a standard process. This process includes deploying/replicating code from the developer's sandbox instance to various other instances for integration and testing, and final deployment to Production.

The software deployment stages for B2C Commerce development include Sandbox, Build and Merge, Staging, Development, and Production.

The following table describes the software deployment stages :

This process is repeated as the development cycle continues. The development team must determine (based on the number and severity of bugs outstanding):

• When an internal build is ready to be deployed to the Build/Merge instance.
• When the build is ready to be pushed to Staging for replication.
• When the build is ready for Production.