Advanced server deployment features

The WebSphere Commerce Build and Deployment tool provides many advanced server deployment features to support more complex configurations. Ensure that you review this page to find and implement features that may improve your server deployment process.

Remote server deployment

The server deployment process can be configured to deploy remotely to any node in a WebSphere Commerce topology configuration, provided that the server deployment system satisfies all prerequisites required by the WebSphere Commerce Build and Deployment tool. Remote deployment is used by the centralized deployment feature in the build process.

To deploy to a remote database node, configure the database-related properties in WCBD_deploy_server_dir/deploy-target-env.properties as follows:

  • Set the following properties according to the local environment on the build system:
    • jdbc.driver
    • jdbc.driver.path
  • Set the following properties according to the remote WebSphere Commerce database:
    • db.name
    • db.schema.name
    • jdbc.url
    • datasource.jndi.name

To deploy to a WebSphere Application Server node or cluster on which the WebSphere Commerce application is deployed, configure the properties in WCBD_deploy_server_dir/deploy-target-env.properties related to WebSphere Application Server as follows:

  • Set the following properties according to the local environment on the build system:
    • was.home
    • was.profile.name
    • was.jvm.max.memory
  • Set the following properties according to the remote environment on which the WebSphere Commerce application is deployed:
    • was.application.name
    • was.use.dmgr
    • was.host.list
    • was.port

Deployment to a remote Web server node is handled by the static Web assets deployment step in the server deployment process. Likewise, deployment to a remote WebSphere Commerce server node (that is the node with the WebSphere Commerce installation) is handled by the WebSphere Commerce configuration file synchronization step and the Data Load utility customization deployment step in the server deployment process. Refer to comments in the configuration files and sample scripts for details.

If you have an existing firewall between your two machines, you might need to open the SOAP port and the WebSphere Application Server administration port, so that the build machine can communicate with the stand alone server it is deploying to. Alternatively, if you have a firewall, you might want to copy your deployment package to the remote machine and run the deployment locally instead of using the remote deployment function.

Loading procedural SQL files

Many database management systems support procedural extensions for SQL. Statements written in procedural SQL often require a different delimiter than the default one for regular SQL statements. The deployment process supports loading procedural SQL files with a procedural statement delimiter based on a keyword identifier in the file name. By default, if the base name if a SQL file contains the keyword identifier procedural, it will be loaded with the procedural statement delimiter @. These can be configured as required by changing the procedural.sql.file.name.id and procedural.sql.delimiter properties in WCBD_deploy_server_dir/deploy-target-env.properties respectively.

Loading data using the Data Load utility

The Data Load utility provides an efficient data load solution based on business objects. The deployment process supports loading data using the Data Load utility, which is useful for loading test data and administrative data such as member data. Similar to how other data files are organized in the repository, data and configuration files used by the Data Load utility are put into the dataload subdirectory of the DataLoad project, which is further organized into the common and target-specific subdirectories. The build process will then include these files into the deployment packages. Unless configured otherwise, all files with the name wc-dataload.xml are included for loading. Additional parameters for the Data Load utility command can be included by setting the dataload.params property in WCBD_deploy_server_dir/deploy-target-env.properties. Refer to the Server deployment configuration properties topic for more information on the properties specific to the Data Load utility.

It is recommended that you follow the Data Load best practices as you develop and organize Data Load data and configuration files. To promote reuse of properties defined in the deployment configuration properties file, especially those of the database, consider using variable substitutions by referencing variables in the configuration files and passing the variable values with the dataload.params property mentioned above.

Setting the maximum heap size for wsadmin

Depending on the size of the WebSphere Commerce application with the customization, the application update process may fail due to wsadmin running out of memory. Typically this does not occur, however if it does, open WCBD_deploy_server_dir/deploy-target-env.properties with a text editor and set the was.jvm.max.memory property to a higher value than the default (1024M).

Setting virtual host for new Web modules

The WebSphere Commerce development environment uses a standard virtual host WC_default_host for Web modules. However, in a server environment, this virtual host does not exist and a different virtual host specific for the WebSphere Commerce instance is required. In response this behavior, the Build and Deployment tool provides the option to set virtual hosts for new Web modules that are deployed by the server deployment process. To set a virtual host, open WCBD_deploy_server_dir/deploy-target-env.properties with a text editor and set the virtual.host.mapping.list property according to the comment in the file.

Mapping references for EJB modules

Some EJB modules require references to operate. For example, the WebSphere Commerce service module may contain a EJB module that contains resource references to the WebSphere Commerce data source, which differ between WebSphere Commerce instances and the WebSphere Commerce development environment. For this reason, the WebSphere Commerce Build and Deployment tool provides a means to map EJB references and resource references to EJB files in the server deployment process.

A mapping option file is used to define the mappings to be applied during the WebSphere Commerce application update. The file , in comma-separated values (CSV) format, lists parameters that describes an individual mapping. The parameters are specified, in order:

  1. The module name, for example Project-Server
  2. The mapping option, for example MapEJBRefToEJB
  3. Any other parameters required by the specified mapping option
Mapping options supported by the WebSphere Commerce Build and Deployment tool

Mapping options supported by the WebSphere Commerce Build and Deployment tool

Mapping Option Parameter Required
MapEJBRefToEJB EJB name Yes
Resource reference Yes
Class Yes
Target resource JNDI name Yes
MapResRefToEJB EJB name Yes
Resource reference Yes
Resource type Yes
Target resource JNDI name Yes
Login configuration name No*
Properties No*
Extended data source properties No*

* The optional values must be set to the empty value in the CSV file.

These option-specific parameters correspond to a subset of the AdminApp object update options for the wsadmin scripting interface. For more information, see Options for the AdminApp object install, installInteractive, edit, editInteractive, update, and updateInteractive commands using wsadmin scripting. For convenience, the following substitution tokens can be used so that some parameters do not need to be hardcoded outside of the server deployment configuration:

Table 1. Substitution tokens
Token Substituted value
@WC_DATA_SOURCE_JNDI_NAME@ The value of the datasource.jndi.name property in the server deployment configuration file.

The following is an example of the mapping option file that maps the WebSphere Commerce data source to the Project and ProjectServicesImpl beans in the Project-Server EJB module:

Project-Server,MapResRefToEJB,Project,jdbc/WCDataSource,javax.sql.DataSource,@WC_DATA_SOURCE_JNDI_NAME@,,,
Project-Server,MapResRefToEJB,ProjectServicesImpl,jdbc/WCDataSource,javax.sql.DataSource,@WC_DATA_SOURCE_JNDI_NAME@,,,

After following the above instructions to create the mapping option file, place it in WCBD_deploy_server_dir. Then open WCBD_deploy_server_dir/deploy-target-env.properties with a text editor and set the mapping.option.file property to the file path.

Deleting files during partial application update

The partial application update functionality from WebSphere Application Server supports the deletion of files from an application using the special ibm-partialapp-delete.props files. Since the WebSphere Commerce Build and Deployment tool leverages partial application update, this file deletion feature can also be used if required.

In most cases, deleting files from the WebSphere Commerce application is a one-time task. As such, it is recommended that the ibm-partialapp-delete.props files are not checked into the repository permanently. Instead, when files need to be deleted from the application, the ibm-partialapp-delete.props files can be added to WCBD_deploy_server_dir/source/wc.ear after the server deployment package is installed. These files will be included into the partial application archive file for update in the server deployment process. Depending on which module scope the files to be deleted are located, the ibm-partialapp-delete.props file may need to be created at different location. For details on how to create and structure the ibm-partialapp-delete.props files, see Adding to, updating, or deleting part of an application through programming.

E-mail notifications of deployment status

The server deployment process can be configured to send out e-mail notifications upon success and failure. For failure notifications, the archived deployment log file is attached for convenience. Follow the steps below to enable this functionality in the deployment settings:

  1. Open WCBD_deploy_server_dir/deploy–target-env.properties with a text editor and set the properties under the "Properties for e-mail notification" section accordingly. Refer to the comments in the file for details.
  2. If the SMTP server requires authentication, open WCBD_installdir/deploy-target-env.private.properties file with a text editor and set the following properties.
    • mail.user
    • mail.password

Additional logging and tracing

Ant provides both a verbose and a debug option to provide additional tracing that may be useful for problem determination. To enable verbose mode, provide either the-v or -verbose option when calling the wcbd-ant.bat or wcbd-ant command to run the server deployment process. Likewise, to enable debug mode, provide either the-d or -debug option when calling the wcbd-ant.bat or wcbd-ant command to run the server deployment process.

The WebSphere Commerce Build and Deployment tool provides a custom logger that captures performance data of the build and deployment processes. The logger outputs the start and end time, as well as the elapsed time for each target that is run, to the console. The following is a sample section of the performance data produced by the logger for the static-web-deploy target in the server deployment process:
[exec] [Wed, 28 Oct 2015 15:58:06 -0400] wcbd-deploy > static.web.deploy
[exec]
[exec] static.web.deploy:
[exec] [echoNL] Deploying web server assets with 
C:\IBM\WCDE_ENT80\wcbd\deploy-server-workspace\wcbd-deploy-server-empty/static-web-deploy-local.xml.
[exec] [Wed, 28 Oct 2015 15:58:06 -0400] static-web-deploy-local > all
[exec]
[exec] all:
[exec] [copy] Copying 3 files to C:\web-server-root
[exec] [Wed, 28 Oct 2015 15:58:06 -0400] static-web-deploy-local < all (0 seconds)
[exec] [Wed, 28 Oct 2015 15:58:06 -0400] wcbd-deploy < static.web.deploy (0 seconds)
To use the logger, provide the following options when calling the wcbd-ant.bat or wcbd-ant command to run the server deployment process:
-logger com.ibm.commerce.wcbd.ant.logger.PerformanceLogger

Note that Ant does not capture the verbose, debug nor logger output in the log file normally generated by the server deployment process. The additional output will only be displayed in the console, so the standard output and error streams should be redirected to a separate log file when running the server deployment process with these logging and tracing options. This can be done by appending the following options when calling the wcbd-ant.bat or wcbd-ant command to run the server deployment process, where log-file is the log file to which the console output is written:

> log-file 2>&1