Level: Intermediate Brian Lima (blima@ca.ibm.com), IBM WebSphere Commerce Developer Readiness
Lorilee Rojas (ljrojas@ca.ibm.com), IBM WebSphere Commerce Developer Readiness
20 Oct 2004 This article describes how to use the WebSphere Commerce auto build and deploy tool, which automates the task of deploying code assets (EJB files, commands, JSP files, properties files) from a WebSphere Commerce development environment to a WebSphere Commerce server environment.
Introduction
Deploying IBM® WebSphere® Commerce code assets (EJB files, commands, JSP files,
properties files, and so on) from a WebSphere Commerce development environment to a WebSphere Commerce
Server environment is a manual and repetitive task. The new WebSphere Commerce
auto build and deployment tool (hereafter called the auto-deploy tool) automates this task and reduces human error.
You can also use the tool to deploy assets to another
WebSphere Commerce development environment. The tool also improves productivity by reducing the time required to deploy code.
A key benefit of using this tool is deploying to another WebSphere Commerce
development environment.
You can use this function to synchronize two development environments. This allows a new developer to quickly get
started with the development process.
The auto-deploy tool packages or builds changed code assets from a development environment, for deployment to another environment.
Figure 1 shows an overview of the auto-deploy process. You can extract the changed source code from either a team environment or
source control repository (A), or directly from the Toolkit's workspace (B). The build phase generates a deployable package
(auto-deploy package) that you can use to deploy to a target environment. The target environment is either another Toolkit (1), or a
WebSphere Commerce Server runtime environment (2a, 2b), including a clustered environment.
Figure 1. Auto-deploy tool process overview
The auto-deploy tool is written entirely as an ANT script. You can extend it to suit your needs.
There are two parts to the tool:
- The build process packages the assets you choose to build (controlled using a properties file) and generates an
autodeploy.jar file, along with two scripts that automate the deployment on to your target environment.
- The deploy process takes the
autodeploy.jar file and deploys the assets (EJB
JARs, custom logic JARs, JSPs, properties files, and so on) to the right places in the target environment. This includes copying files, updating
classpaths, and updating application and deployment XML files.
Note: The Toolkit in this article refers to the WebSphere Commerce development environment or the WebSphere
Commerce Toolkit.
Before installing the auto-deploy tool
Before you install the auto-deploy tool, do the following steps:
- Install WebSphere Studio Application Developer V5.1 (hereafter called WebSphere Studio) or later.
- Install one of the WebSphere Commerce Developer Editions (Express, Professional, or Business) V5.6 or later.
- Download and uncompress Ant-Contrib by doing the following steps:
- Go to the Ant-Contrib site.
- Click on the downloads link, select the ant-contrib-1.0b1-bin.zip package and follow the download instructions.
- After you download the the zip file to your system, uncompress the file to a folder on your system.
- If you are developing in a team environment and are using a Source Control Management (SCM) system, install the
SCM Client necessary to extract code for SCM. The auto-deploy tool provides scripts for building from two SCM systems,
Concurrent Version System (CVS) or Rational ClearCase.
- If you are using CVS for SCM, you can download and install WinCVS as the CVS Client. Alternatively, you can use the integrated CVS client provided in WebSphere Studio.
- If you are using Rational ClearCase for SCM, install Rational ClearCase Lite provided with the WebSphere Studio install package and use the WebSphere Studio environment as the ClearCase Client.
The build scripts expect a pre-defined structure for the assets within the SCM system.
For more details, refer to the Location of assets section below.
 |
Installing the tool
To install the auto-deploy tool, do the following steps:
- Download and save the provided AutoDeployTool.zip file to your machine.
- Uncompress it to a folder called Deploy under the workspace folder of your Toolkit environment. Import the project into your Toolkit
workspace using the Existing Project into Workspace option.
- Within WebSphere Studio, right-click on the Deploy project, select Properties and click on
Java Build Path.
- Once in the Java™ Build Path dialog, click the Libraries tab. Click on the Add External Jars button to add
websphere.jar, which is located in the
WC-toolkit-dir\AppServer\lib directory.
- Click OK after adding the JARs and click OK on the other prompts.
The build process
The build process consists of:
- Placing updated code assets in the correct location so the tool can pick them up.
- Updating the build properties file to specify build environment options and list assets that need to be built.
- Initiating the build process from within the Toolkit.
Location of assets
The source of code assets for a build is either the Toolkit's install directory, or an SCM system for team development.
If you are using a SCM system, then the directory structure within the SCM system should mirror a subset of the Toolkit's
install directory. At a minimum, create a workspace and xml directory in the SCM system.
You can specify the following types of assets for a build:
- EJB projects
- Java projects
- Connector projects
- Web projects (modules)
- XML policies
- DDL files
- DML files
- Data load files
EJB projects, Java projects, Connector project, and Web projects are directly under the workspace directory. For example, if you have
MyCustomEJBProject and WebSphereCommerceServerExtensionsData projects,
they are in the workspace\MyCustomEJBProject and
workspace\WebSphereCommerceServerExtensionsData directories.
Run the XML policies for any new commands as part of deploying new commands to the deployment environment. Place the XML
policies files in the xml\policies\xml directory.
These files are copied over and during deployment and are run
against the deployment database using acpload.
You may have created new tables in your database, and created corresponding EJBs. You can provide the Data Definition Language
(DDL) files, so you can create the corresponding tables in the target environment's database. These DDL files have an extension
of .ddl or .sql and are placed into the workspace\db\Schema directory.
You can also specify Data Manipulation Language (DML) files as code assets. DML files have an extension of .sql and
contain insert or update SQL statements. Place these assets in the workspace\db\sql directory.
The DDL and DML files are copied over to the target environment during deployment and executed against the target database.
You can use the massload utility or the idresgen utility to load and specify the data load files.
If the XML data files do not
need to be massloaded, place them in the workspace\db\massload directory.
Place files that need to be idresloaded and massloaded
in the workspace\db\idresload directory.
These files are copied over and during deployment and are run against the
deployment database using idresgen and massload.
Table 1 summarizes the assets type, location in the source system, location in the auto-deploy
package, and additional information.
Table 1. Asset types
|
Asset type
|
Source location
|
Asset location in auto-deploy package
|
Additional information
| |
EJBs
|
workspace\ejb_project
|
ear\ejbmodules\ejb_project
|
Specify which projects to build in the properties file.
| |
Java Project
|
workspace\java_project
|
ear\logic\java_project
|
Specify which projects to build in the properties file.
| |
Connector Project
|
workspace\connector_project
|
ear\connectormodules\connector_project
|
Specify which projects to build in the properties file.
| |
Web Modules
|
workspace\webModule
|
ear\webmodules\webmodule
|
Specify which projects to build in the properties file.
| |
XML policies
|
xml\policies\xml
|
wcs\xml\policies\xml
|
All files
| |
DDL
|
workspace\db\Schema
|
wcs\db\Schema
|
All files
| |
DML
|
workspace\db\sql
|
wcs\db\sql
|
All files
| |
MassLoad
|
workspace\db\massload
|
wcs\db\massload
|
All files
| |
IDResolvable files
|
workspace\db\idresload
|
wcs\db\idresload
|
All files
|
Example modules file for your CVS repository
The location of assets within your CVC repository is important. They need to be described in the modules file found in the drive\CVSROOT directory of your CVS server. There is some linkage between the way the repository is set up and how the build tool extracts assets from the repository. In particular, the build tool looks for the package in CVS that you specify in the build.properties file
desrcibed in the next section. You must set up the package in CVS so that it includes all of the customized assets.
To help you setup your CVS repository to work with the build tool, you can use the
ExampleCVSmodulesFile.txt file in the
AutoDeployTool.zip package. Examine this file, and use it as guidance to update your existing drive:\CVSROOT\modules file.
Property files for the build
The auto-deploy tool provides several property files for specifying build options. Which property file to modify,
and its corresponding XML file, is dependent on the environment from which the auto-deploy package is built. You have two choices:
- Building the auto-deploy package directly from the Toolkit's workspace.
- Building the auto-deploy package from a SCM system, such as CVS or Rational ClearCase, for team development.
The property files provided as part of the auto-deploy tool specify the build environment and information on build options.
Therefore, it is important to setup the property keys correctly so that you can set up and update them correctly in the property files.
Build property files
The build.properties file contains properties that are common to both team and non-team environment builds. When using SCM systems and building in a team environment, use
build.properties in conjunction with the property files specific to the SCM (described below).
A non-team environment implies building the auto-deploy package directly from the Toolkit's install directory, you only
need to update build.properties.
To edit and set the build properties, expand the Deploy project in the Project Navigator View within the Toolkit. Click
build.properties file to edit it. Table 2 summarizes the property keys that you can update and the allowed values.
Table 2. Property keys and their values
|
Key
|
Description
|
Mandatory/optional
|
Valid values
|
Example
|
wsad_install_location
|
The directory where WebSphere Studio is installed. |
Mandatory
|
WebSphere Studio install directory
|
D:\WSAD5.1 |
toolkitdir
|
The directory where the WebSphere Commerce 5.6 Toolkit is installed. |
Mandatory
|
Toolkit install directory
|
D:\WCToolkitBE56 |
ant_contrib_location
|
The directory where ant-contrib-1.0b1.jar is located on your system. |
Mandatory
|
Valid directory name |
D:\ |
builddir
|
The directory where the WebSphere Commerce assets will be built. |
Mandatory
|
An existing directory name |
D:\build |
ejb_projects
|
A comma separated list of EJB projects that need to be built.
|
Optional
|
|
WebSphereCommerceServerExtensionsData, myCustomEJBProject |
target_db
|
The target database that will contain the deployed WebSphere Commerce assets.
This information is used to convert EJB meta-data to the target database.
|
Optional. Mandatory if you specify ejb_projects.
| db2, oracle®
|
db2 |
ejb_jndi_name
|
The JNDI name that will be used in the deployment descriptor. The EJB project is updated with this JNDI name.
This should line up with the datasource information of the WebSphere Commerce instance you are deploying to.
|
Optional. Mandatory if you specify ejb_projects.
|
|
jdbc/WebSphere Commerce DB2 DataSource instance1 |
ejb_manifest
|
The ejb_manifest contains the class path information for the EJB.
The class path information is separated by a space.
This is used to update the MANIFEST.MF of the EJB Project. |
Optional. Mandatory if you specify ejb_projects.
|
|
Catalog-ProductManagementData.jar,
Enablement-BaseComponentsData.jar,
Enablement-IntegrationData.jar,
Enablement-RelationshipManagementData.jar |
java_projects
| A comma separated list of Java projects that need to be built.
|
Optional |
|
WebSphereCommerceServerExtensionsLogic |
connector_projects
| A comma separated list of connector projects that need to be built.
|
Optional |
|
JCAConnectorProject |
web_projects
| A comma separated list of Web modules and projects that need to be built.
|
Optional |
|
Stores, Commerce Accelerator, Organization Administration |
code_dependencies
| Captures directories or JAR files that will be needed in the compilation of the EJBs and the Java projects.
This is a comma separated list. You can add multiple folders and JAR files. |
Optional |
|
AppServer/lib, AppServer/lib/jaxb,
workspace/WebSphereCommerce
ServerExtensionsData, workspace/WebSphereCommerce
ServerExtensionsLogic, workspace/GWOrdersData |
ejb_classpath
| The classpath you want to provide for compiling EJB projects. |
Optional. Can use to provide additional classpath for compiling EJB projects. |
|
|
generated_DDL
| Specifies if the tool should include files, such as Table.DDL, that are created automatically by WebSphere Studio Application Developer. In general, if you have your own scripts to create tables, set this value to "no". |
Required. | no, yes
|
|
Additional property files for team environments
A team development environment implies that you are using a Source Control Management (SCM) system for the developers on a project to manage code and release versions. The auto-build and deploy tool provides additional build and deploy scripts for two different SCM systems, CVS and Rational ClearCase. The corresponding property files for these two environments are cvs.properties and ccase.properties that you can use in conjunction with the build.properties file. You can modify or extend them as a base to develop build scripts for other SCM systems you may have.
CVS specific properties (cvs.properties file)
When using CVS as the SCM, in addition to updating the property keys described above in the
build.properties file, you also need to update the property keys in the
cvs.properties file as shown in Table 3.
Table 3. CVS specific properties
|
Key
|
Description
|
Mandatory/optional
|
Valid values
|
Example
|
cvs_root
|
This contains the CVSROOT variable, such as the connection information for your CVS system. |
Mandatory
|
|
:pserver:username:password@hostname:/cvsdirectory |
cvs_package
|
The package or module to check out. |
Mandatory
|
|
commerceteamenv |
checkout_dest_dir
|
The directory where the code will be checked out from the CVS system. |
Mandatory
|
|
D:\ |
Rational ClearCase specific properties (ccase.properties file)
When using Rational ClearCase as the SCM, in addition to updating the property keys described above in the build.properties file, you also need to update the property keys in the ccase.properties
file as shown in Table 4.
Table 4. Rational ClearCase specific properties
|
Key
|
Description
|
Mandatory/optional
|
Valid values
|
Example
|
ccase_viewpath
|
This contains the path to the ClearCase view file or the directory that the command will operate on. |
Mandatory
|
|
c:\views\viewdir\afile |
ccase_version
|
Allows checkout of a version other than the latest. |
Optional
|
|
|
checkout_dest_dir
|
The directory where the code will be checked out from the CVS system. |
Mandatory
|
|
D:\ |
Database properties for deployment to development environment
If you deploy your code into a development environment, you can use the db.properties file to hold information for establishing a connection to your development database. If you are using a Cloudscape database, you should not need to update this file. If you are using DB2® or Oracle® for your development database type, updates will be required. Table 5 describes this file.
Table 5. db.properties file
|
Key
|
Description
|
Mandatory/optional
|
Valid values
|
Example
|
jdbcDriver
|
The JDBC driver that is used for Cloudscape. |
Mandatory
|
|
com.ibm.db2j.jdbc.DB2jDriver |
jdbcUrl
|
JDBC URL for Cloudscape database. |
Mandatory
|
| jdbc:db2j:${demo}/db/mall
|
dbUser
|
User to connect. |
Mandatory
|
|
user |
dbPassword
|
Password for database user. |
Mandatory
|
|
password |
dbType
|
Indicates flag for development database type. |
Mandatory
| DB2J, DB2, oracle
|
DB2J |
jdbcDriverLocation
|
Location of JDBC driver JAR on the system. |
Mandatory
|
|
${demo}/AppServer/classes/db2j.jar |
Initiating the build
Figure 2 shows an overview of the build process. The assets to be built are updated directly under the Toolkit's install directory,
and the build.properties file is updated with the correct information.
Figure 2. Building from a non-team development environment
To create the auto-deploy package, within the Toolkit, right click on the
build.xml file in the Deploy project, then click RunAnt.
Running the build in a team environment
For team environments where you use the SCM system, the tool provides scripts you can use with CVS or Rational ClearCase.
The process to initiate the build in both cases is similar.
CVS as SCM
Figure 3 shows an overview of the build process. The assets to be built are checked in the
CVSROOT/workspace and CVSRoot/xml directories,
and the cvs.properties file is updated with the correct information.
A module or package definition are created in CVS that includes CVSROOT/workspace,
CVSROOT/xml, and any other directories that you want to include as part of the build.
For information on using CVSROOT and creating CVS modules, see the online
CVS documentation.
Figure 3. Building from CVS as SCM
To create the auto-deploy package, within the Toolkit, right click on the
cvs.xml file in the Deploy project, then click RunAnt.
Rational ClearCase as SCM
Figure 4 shows an overview of the build process. The assets to be built are checked in the
ccase_viewpath/workspace and
ccase_viewpath/xml directories, and the
ccase.properties file is updated with the correct information.
You need to create a Versioned Object Base (VOB) to contain the files and directories. Before you can put the assets into
your VOB, create a view. Once you create the view, then add the files and directories to thee view and put under source control management.
Figure 4. Building from ClearCase as SCM
To create the auto-deploy package, within the Toolkit, right click on the ccase.xml file in the Deploy project,
then click RunAnt.
Next steps
Copy the auto-deploy package file to your environment. Unzip or unjar the file as
appropriate and follow the deployment procedure to deploy the assets to a target WebSphere Commerce environment.
Deploying WebSphere Commerce build assets to a server
Figure 5 shows the deployment process and the options available.
After the build is done and the assets are packaged, three deployment strategies are available to you for deploying the
delta package to the server environment:
- Deploying to a production environment
- Deploying to a test or staging environment
- Deploying WebSphere Commerce build assets to a development environment
Figure 5. Overview of deploy process
Deploying to a production environment
The auto-deploy tool provides scripts to deploy the packaged assets to a production environment. The deployment procedure
takes a WebSphere Commerce EAR file (commerce.ear) as input, updates the input EAR file with the assets from the auto-deploy package
and produces another EAR file, autodeploy-yyyymmdd.ear, that contains the base EAR file
and auto-deploy assets. The auto-deploy
tool then updates the WebSphere Commerce application in the WebSphere Application Server environment with the newly created EAR file, autodeploy-yyyymmdd.ear.
After you install the EAR file, autdeploy-yyyymmdd.ear, additional deploy steps such as new creating new tables, processing of SQL files, executing acpload for XML policies, and running idresolve and massload for data loading are executed automatically if you specified these files in the build phase. For example, if you specified a table creation script inworkspace\db\schema, it runs automatically.
This is the recommended approach for deploying to a production environment. The key benefit is that, as part of the
deploy procedure, an output EAR file (autodeploy-yyyymmdd.ear) is generated that you
can use to keep track of different builds version
of the EAR file. This provides an easy mechanism to go back to an earlier build if needed, or even to the base EAR file,
commerce.ear.
If you have WebSphere Commerce installed and an instance configured, you can find the base commerce.ear
file in the
WASInstallDir\config\cells\nodename\applications directory.
Figure 6. Deploying to production server environments
To deploy the EAR file using the WebSphere Application Server Administration Console, use one of the following commands:
- Windows®
deploy.cmd java_home server_ear - AIX®
./deploy.sh java_home server_ear - Solaris®
./deploy.sh java_home server_ear
This process prompts the user to provide the WebSphere Commerce base EAR file (commerce.ear), WebSphere Application Server install directory, WebSphere Commerce Server install directory, WebSphere Commerce instance name, and
WebSphere Appplication Server node name as parameters.
The process deploys the package as described above.
Deploying to a test or staging environment
The auto-deploy tool provides scripts to deploy the packaged assets to another test or staging environment.
The process deploys the auto-deploy package assets to a WebSphere Commerce ear folder under
the installedApps directory for WebSphere Application Server.
Figure 7. Deploying to a server
To deploy directly to a server environment, use one of the following commands:
- Windows
deploy.cmd java_home server - AIX
./deploy.sh java_home server - Solaris
./deploy.sh java_home server
This process prompts the user to provide the WebSphere Application Server install directory,
WebSphere Commerce Server install directory, WebSphere Commerce instance name, and WebSphere Application Server node name as parameters.
The process deploys the packaged assets to the installedApps/WC_instance_name.ear folder.
It also updates the appropriate
information in application.xml and deployment.xml files
located in the config/cells directory to ensure new EJBs,
connector projects, and so on get picked up.
After the ear folder tree is updated, additional deploy steps such as creating new tables, processing of SQL files, executing acpload for XML policies, and running idresolve and massload for data loading are executed automatically if you specified these files in the build phase. For example, if you specified a table creation script in the
workspace\db\schema directory, it runs automatically.
As an example, you can do the following:
- Navigate to the directory where you extracted the deployment package:
cd C:\Build\TodaysBuild
- Enter the following command, such as:
deploy.cmd C:\Program Files\WebSphere\AppServer\java server
- Once the command starts to run, you are prompted for the following values:
- Directory where you extracted the deployment package. For example:
C:\Build\TodaysBuild
- WebSphere Commerce install directory. For example:
C:\Program Files\WebSphere\CommerceServer56
- WebSphere Application Server install directory. For example:
C:\Program Files\WebSphere\AppServer
- The WebSphere Commerce instance name. For example:
demo
- The node name of your Application Server. For example:
<machine hostname>
Deploying WebSphere Commerce build assets to a development
environment
The auto-deploy tool provides scripts to deploy the packaged assets to another development environment. This provides
a quick way to synch up another development environment with the new build.
Figure 8. Deploying to another development environment
Use the following command to run this option:
- Windows
deploy.cmd java_home dev
As an example, you can do the following:
- Navigate to the directory where you extracted the deployment package:
cd D:\Build\TodaysBuild
- Enter the following command:
deploy.cmd D:\WSAD511\runtimes\base_v5\java dev
- Once the command starts to run, you are prompted for the following values:
- Location of the extracted deployment assets. For example:
D:\build\TodaysBuild
- Location of the toolkit where the code will be deployed. For example:
D:\WCToolkitBE56
- Location of WebSphere Studio Application Developer on your development machine. For example:
D:\WSAD511
This deploys the source code for EJBs and Java and Connector projects to the specified workspace
directory. Web projects are copied to the right location under the workspace directory.
After the WebSphere Commerce assets are deployed, deploy steps like creating new tables, running sql files,
acpload for xml policies, and idresolve and massload processes are run against the database pointed by the development environment.
Conclusion
This article described how to use auto-deploy tool to build and deploy WebSphere Commerce assets.
Using this tool eliminates the manual and repetitive task of deploying code assets from a development environment to a server environment.
It also significantly reduces the amount of human error when deploying these assets.
The build process describes using the tool for structuring and building assets in a team and non-team development environments.
The deploy process describes deployment to different WebSphere Commerce environments and the options
for running the deployment against different environments.
Download | Description | Name | Size | Download method |
|---|
| WebSphere Commerce auto build and deployment tool | AutoDeployTool.zip | 74KB | FTP |HTTP |
|---|
Resources - developerWorks WebSphere Commerce zone.
Access to WebSphere Commerce how-to articles, downloads, tutorials, education, product information, and more.
- WebSphere Commerce V5.6 Information Center.
View the online help for WebSphere Commerce 5.6 without installing it.
- Browse for books on these and other technical topics.
- WebSphere forums.
Product-specific forums where you can ask questions and share your opinions with other WebSphere users.
- WebSphere Commerce V5.5 Handbook, Customization and Deployment Guide.
Redbook to help you design, develop, implement, deploy, and manage a WebSphere Commerce V5.5 runtime environment and store.
About the authors | | | Brian Lima is a software developer at the IBM Toronto Lab in Toronto, Ontario, Canada. His responsibilities currently include working on the WebSphere Commerce Development Environment. |
| | | Lorilee Rojas is a software developer at the IBM Toronto Lab in Toronto, Ontario, Canada. Her responsibilities include improving productivity for WebSphere Commerce developers.
|
Rate this page
| 
