WebSphere Commerce Version or later

Converting a staging server into a workspace-enabled authoring server

The following section outlines the high-level steps that must be followed to convert a WebSphere Commerce version 8 staging server into a workspace-enabled authoring server.

Note: If you are migrating from a previous version of WebSphere Commerce, you must first complete the migration to version 8 before converting a staging server into a workspace-enabled authoring server.
For more information on the authoring server, and workspaces, see Workspaces overview.

Before you begin

If you are converting a live production environment, you must carefully consider your conversion plan. The planning phase should encompass the same considerations as a migration. This includes backup and restoration, testing, and your plans for switching over the deployment in place.

For general information and guidelines on migration planning, see Planning to migrate WebSphere Commerce.

Important: It is essential to have full backups of your staging database and instance in the event that the conversion is unsuccessful. These backups will ensure that the server can be restored.


  1. Reconfigure the staging instance as an authoring instance, with workspaces enabled.
    1. Locate, if possible, the createInstance.properties file that was used to create the original staging instance.

      This file can typically be found within the WC_installdir/instances/instance_name/properties/ directory.

      This is the configuration properties file that was generated by the Configuration Manager when the instance was created. This file is used as the input to all of the Ant scripts that were subsequently run to create the instance. Using this file will ensure that your newly constructed environment will be identical to your existing one, with the addition of the workspaces component.

    2. Construct a new createInstance.properties file that is customized to your authoring environment.

      Base this file on the existing staging instance settings contained in the original file, and include the workspace-enabling configuration settings.

      You can use the Configuration Manager without actually creating an instance to obtain a new version of this file that will contain the workspace-enabling settings. For more information on generating this file with the Configuration Manager, see Generating the createInstance.properties file. Merge the workspace settings that have been enabled in the newly generated file with the one that you are constructing.

      Important: Ensure that the file is correctly formed, and otherwise identical to the original beyond the enablement of the workspaces component.

      Pay specific attention to content management (CM) related properties which need to be defined correctly.

      An example of this section is as follows:
      isContentManagement=true - this to allow the ant scripts to run.
      cmDBUserID=db2user - This is the production DB user that will end up in the JaasAuthData
      cmTargetApp=WC_demo - Not sure if really necessary. It does not end up in WAS, but it may be set in other conf files.
      cmDatasourceName=WebSphere Commerce DB2 Publish DataSource stage - The name of the quick publish datasource that will be created in the staging environnment.
      cmDatabaseType=db2 - DB type of the production DB.
      cmDBName=WCDB - DB name of the production DB.
      cmDbServerName=WC8MLG.acme.com - Servername of the production DB.
      cmDbServerPort=50000 - Port of the production DB.
      cmJdbcURL=jdbc:db2://WC8MLG.acme.com:50000/WCDB - JDBC URL of the production DB.
    3. Using the newly constructed createInstance.properties configuration file, run the workspace enablement Ant target, ConfigureWorkspaceComponent.
      The specific syntax for this command is platform dependent and described in the ConfigureWorkspaceComponent documentation.
      An example of running this command on Windows is as follows:
      config_ant.bat -DinstanceName=stage -DcmDBUserPwd=password -DdbaPassword=stage -DdbUserPassword=stage ConfigureWorkspaceComponent 1>..\logs\ConfigureWorkspaceComponent.log 2>&1
      - cmDBUserPwd (ie. "password") is the password for production DB user.
      - instanceName (ie. "stage") is the instance name for the staging instance.
      - dbUserPassword (ie. "stage") is the password for staging DB user.
      - dbaPassword (ie. "stage") is the password for staging DBA user.

      This Ant target will call the dependent Ant targets and set up the workspaces component on your environment. For more information on any specific Ant target, see Ant targets.

    4. Restart the server.
  2. Verify that the enablement of workspaces completed without issues.
    1. Check the log that was generated by the Ant target for any errors.
    2. Confirm that the workspace authoring schema was added to the staging database. You can do this by querying the database with the following SQL statement:
      select * from wcw101.catentry
    3. Confirm that the workspace Tasks application is present in the Management Center for WebSphere Commerce.
  3. Reconfigure the quick publish connection between your authoring and production instances. This is done by rebinding the content management utility EJB to the quick publish datasource.
    1. Back up the original JAR file.
      Create a backup of WAS_installdir\profiles\stage\installedApps\WC_stage_cell\WC_stage.ear\Enablement-BusinessContextEngineAdvancedInterface.jar.
    2. Complete steps 1 - 21 of Deploying J2EE assets for an entire module.
      In step 15, on Install new application:
      • Select Step 4: Map resource references to resources.
      • Modify the Target Resource JNDI Name to reflect the correct publish data source. Select the correct datasource name from the drop down selection. For example, WebSphere Commerce DB2 Publish DataSource stageInstanceName.
    3. Restart the server.
  4. Test that the quick publish connection is functioning as expected.
    1. Test the quick publish JDBC datasource connection in the WebSphere Application Server Administrative Console under datasources.
    2. Test customer segment exporting to confirm that customer segment data can be exported from the production environment to the authoring environment.
      To export customer segment information, see Exporting customer segment information.
    3. Test the workspace emergency fix scenario to confirm that workspaces are working as expected, and that a simple emergency fix can be published from the authoring environment to the production environment.
      To publish an emergency fix, see Workspace example scenario: Emergency fixes.


Your staging environment is now reconfigured as a workspace-enabled authoring environment.