Deploying WebSphere software with Rational Automation Framework

IBM® Rational® Automation Framework is a server-based software product that can automate many IBM WebSphere® middleware distribution and administration activities. To demonstrate, this article explains the simple process of configuring the Rational Automation Framework environment to create a typical sample IBM WebSphere Application Server cell that contains two nodes, an IBM HTTP Server, and an application cluster.

Werner Vanzyl (, Senior Managing Consultant, IBM

Author photoWerner Vanzyl is a Certified IT Specialist with IBM Software Services for WebSphere. He has over 15 years of experience working with a variety of software products, including IBM software and other development platforms. Currently, he consults on a daily basis with IBM customers in the areas of business process and workflow development, implementation, and deployment.

08 February 2012

Also available in Chinese


IBM Rational Automation Framework is a server-based software product that can automate many IBM WebSphere middleware distribution and administration activities. Due to the repetitive nature of the tasks involved, distributing software by installing and creating an IBM WebSphere Application Server Network Deployment cell can be time consuming and potentially error prone. By leveraging Rational Automation Framework to distribute product binaries, install the software, and create the cell, this process can be streamlined and customized to fit your needs. Best of all, the process becomes repeatable and predictable, saving time and valuable resources.

This article explains the simple process of configuring the Rational Automation Framework environment to create a standard WebSphere Application Server cell that contains two nodes, an IBM HTTP Server, and an application cluster; a basic, typical scenario.

In the example described here, the Rational Automation Framework media tree will be configured with the product software, an environment will be generated in Rational Automation Framework, and the environment creation project will be executed. At the end of the activities, the environment will be validated and the next steps will be discussed.


This article assumes that Rational Automation Framework has been installed on a framework server and that you have two nodes available to act as the WebSphere Application Server nodes in the topology. Also, WebSphere Application Server V7 or later, IBM HTTP Server, and HTTP Plug-in are installed and available, with Fix Pack 17 for each product downloaded and applied.

WebSphere Application Server topology

Perhaps the most common topology for a WebSphere Application Server Network Deployment cell consists of:

  • A deployment manager (Dmgr).
  • Node agents on each of the federated nodes.
  • Clusters where your application will run.
  • An HTTP server that will route web traffic to the cluster members in the cell.

You will build this environment using an automated process captured in Rational Automation Framework. When completed, the cell will be started and it will be ready for applications to be installed (which can be done through Rational Automation Framework as well). As shown in Figure 1, all the information required by Rational Automation Framework can quickly and easily be captured to simplify the process of generating the environment.

In Rational Automation Framework, the representation of all these components is called an environment, which is the cornerstone of the automation concept. The environment captures all details of the processing environment and is applied to a job when it is executed.

Figure 1. WebSphere topology being created
A pixel ruler showing the maximum width of an image used for an article (580 pixels)

The framework server and WebSphere Application Server cell configuration

Framework server

Rational Automation Framework is a server-based product. The system where the server component of Rational Automation Framework is installed is referred to as the framework server. Rational Automation Framework provides two remote methods of access: though an Eclipse client and the IBM Rational Build Forge Management Console. Rational Automation Framework also provides a command line interface that can be used to execute actions from the framework server.

If you adopt automation, then the framework server can be the central repository for all WebSphere Application Server cell configuration within the enterprise. This means that all configuration changes can be made on the framework server first, and then applied to the specified target environment.

When managing a configuration in the framework server repository, the configuration can then be promoted and applied to multiple WebSphere Application Server cells managed by Rational Automation Framework. A simple example is a JDBC datasource configured in a development environment. By saving the configuration in the framework server, the datasource can be created in the test, QA, and the production systems exactly as in development, eliminating any configuration errors that might occur when creating these environments with the admin console. By using the promotion features in Rational Automation Framework, configurable values (such as database URL, name, and so on) can be modified for each environment, with the basics left untouched.

This practice can now be expanded to include the configuration of a complete WebSphere Application Server cell, as well as the installation of the software and configuration of the resources. This practice can save considerable time, and be practically error free.

Configuration of the media tree

Location of RAF_HOME

The term RAF_HOME is used throughout this article to represent the installation location of Rational Automation Framework on the framework server. An example of such a location would be /opt/IBM/RAFServer/rafw for a Linux® or a UNIX® system.

The media tree is a folder structure on the framework server that would become a shared location that can be accessed from all the target systems using technology such as NFS protocol. The advantage of using the shared approach is that the product installation files and fix packs won't be transferred to the target system when the software is installed, but rather the files on the shared location will be used by each target system.

This makes the deployment of a new environment considerably faster by eliminating the need to copy the product software to each system that will be in the final cell.

The media tree is located in the RAF_HOME/media folder on the Framework server by default. The location of the media files on the framework server (as well as on the target systems) can be modified by editing the RAF_HOME/ file on the framework server. You can modify the OS-specific values in the media location section for either the framework server or the target systems.

The media tree is organized by operating system, hardware architecture, WebSphere product, product version, and image type. For this example, the environment you are creating in this example will include:

  • WebSphere Application Server V7.0.0.17
  • IBM HTTP Server
  • HTTP Plug-in

Installation will be on a 64 bit, Intel®, Linux system. That means that the software images above should be copied, respectively, to these folders (Listing 1):

  • RAF_HOME/media/linux/X64/was/70
  • RAF_HOME/media/linux/X64/ihs/70
  • RAF_HOME/media/linux/X64/plugins/70
Listing 1. Media location on the Framework server and Target systems
## RAFW_MEDIA_ROOT is the root directory of the media on the Framework Server
## Modify this property if a different media root is required on the 
## Framework Server
## If not specified the default is ${RAFW_HOME}/media

## <OS>_MEDIA_ROOT is the root directory of the media on each Target System 
## according to OS
## The default is ${<OS>_RAFW_HOME}/media
## Modify these properties if a different media root is required on the 
## Target System

LINUX_MEDIA_ROOT=/media   # This entry was modified to represent the actual location

Rational Automation Framework will attempt to use the latest defined version of the product when installing the WebSphere software. This means that if there is a was70_fp17 directory in the patches folder, then Rational Automation Framework will apply Fix Pack 17 to WebSphere Application Server. To override this behaviour, you can modify the RAF_HOME/user/environments/[ENVIRONMENT NAME]/cells/[CELL NAME]/ file to reflect the version of the product that you need to have installed. Update the WAS_FIXES property to match the directory representing the correct version (Listing 2).

Listing 2. Required version of the product
# comma delimited list of fixes to apply to WAS - used by was_common_install_fix_was

Each of the product folders in the media tree consists of a set of sub-folders where the product files are placed. The files placed in each folder differ based on the type of folder. Table 1 describes the type of folders and files.

Table 1. Media tree details
Folder nameDescription
install_imageContains the primary software image obtained from Passport Advantage or product the CDs. If a compressed file (.zip, .gz or .tar) is downloaded, then it would need to be extracted.
patchesContains the cumulative fix packs obtained from IBM Fix Central. The file should be of type .PAK and should not be extracted but left as is.
feature_packsContains any additional WebSphere Feature Packs obtained from the IBM WebSphere product web sites.
update_installer_imageWebSphere Update Installer software obtained from the IBM Update Installer web site. The latest should be used in most cases.
im_install_imageInstallation Manager software for WebSphere Application Server V7.x and higher can be downloaded from the IBM Support site. This is an optional feature that will not be used in this example.
was70_im_repositoryInstallation Manager repository files for specific features and fixes that should be installed with Installation Manager.

Target setup and configuration

A target system is the remote system that will be managed by the Rational Automation Framework automation tooling. Although no Rational Automation Framework specific configuration is needed to access or configure the target system from the framework server, there are some actions that you will take in the scope of this example:

  • The initial installation will be performed as a root user for ease of access and manageability. However, as in many cases, the WebSphere Application Server process will not run as a root user, but rather a dedicated WebSphere Application Server user. When the installation is complete, you will switch to the WebSphere Application Server process user called wasadm. The wasadm user should be created manually on the target systems.
  • You will also use an NFS mount to access the shared media location on the framework server. The process of mounting the shared folder should be done before the installation process is started from the framework server.

Environment Generation wizard

The Environment Generation wizard will create the environment on the framework server, generate the folder structure in the RAF_HOME/user/environments folder, and create a project to generate the environment on the target systems.

The wizard will ask questions to determine the topology of your WebSphere Application Server cell and display additional dialogs to capture more information as needed. The information required is based on that shown in Figure 1. It’s a good idea to draw out a diagram similar to Figure 1 for yourself before you run the wizard.

This action is normally done only once per environment and can be executed from the Eclipse client, Build Forge Management Console, or the command line. The Build Forge Management Console will be used in this example.

In the Management Console, select the RAF tab. Click the Create new WebSphere Cell button, and provide the information shown in Tables 2 through 6 as you click through the panels.

Table 2. Topology information
Product or user template?Product
Environment nameDwWAS7
Cell nameDwWAS7Cell01
Cell typeWebSphere Application Server
WebSphere Application Server version70
Include IBM HTTP ServerYes
Number of IBM HTTP server nodes in cell1
Stand-aloneNetwork Deployment
Number of nodes in cell2
Number of clusters in cell1
OS user nameroot
OS passwordpassword
OS grouproot
Are you using DB2No
Table 3. Deployment Manager Node Configuration
Deployment Manager node nameDmgrNode01
Deployment Manager profile nameDmgr01
Deployment Manager host nameDwWAS7Host01
z/OS SupportNo
Deployment Manager home/opt/IBM/WebSphere/AppServer7
Deployment Manager starting port numberLeave Blank
Enable securityYes
WebSphere Administrator user nameadmin
WebSphere administrator passwordadmin
Table 4. Node Configuration for both the nodes
Node host nameDwWAS7Host01 and DwWAS7Host02
z/OS SupportNo
WebSphere installation directory/opt/IBM/WebSphere/AppServer7
Node nameDwWAS7Node01 and DwWAS7Node02
Profile nameAppSvr01
Profile parent directory/opt/IBM/WebSphere/AppServer7/profiles
Node agent starting port numberLeave Blank
Table 5. Cluster Information
Cluster nameAppCluster01
Cluster nodesCheck both nodes
Number of vertical cluster members1
Cluster member name prefixserver
Cluster member starting port numberLeave Blank
Table 6. IBM HTTP Server Information
Host nameDwWAS7Host01
Node nameDwIHS7Node01
Profile nameihs1
z/OS supportNo
Web Server definition namewebserver
IBM HTTP Server installation directory/opt/IBM/HttpServer7
IBM HTTP Server Plug-in home directory/opt/IBM/Plugins7
IBM HTTP Server HTTP port80
IBM HTTP Server administration port8080
Allow non-root installationNo
Create AdminAuth AccountNo

When the final Next button is clicked, the Update progress output will display. Refresh the status by clicking the Update button. Wait for the project to finish with a PASSED result and a message indicating Generating environment group and project. This is an indication that the environment was successfully generated on the framework server.

Running the Environment Deployment project

On the Console tab, select the Projects menu item in the navigation. A project is a predefined set of steps to accomplish a specific goal on the target systems. When a project is started, a job is created based on the project steps and the supplied environment. After the project is started, the progress of the activities will be viewed as a job.

A new project was created with a name that includes the form that was used (RAFW) plus the environment name and the cell name (Figure 2). This project is used to generate the new environment on the target systems. Select the project name to view the execution options and to start the job.

Figure 2. Project list
A pixel ruler showing the maximum width of an image used for an article (580 pixels)

Click the Start Project button (Figure 3) to continue and create a job that will be run.

Figure 3. Starting a project
A pixel ruler showing the maximum width of an image used for an article (580 pixels)

A job consists of the execution steps as well as the environment. At this point in the process, the environment is displayed and can be modified. The environment is made up of the information provided when the environment was generated.

Review the information that was captured in the environment. If you do see an error, the value can be modified here before the jobs are executed. To save any changes, make sure that the Save Environment property is checked before you execute. For this example, be sure that the mode is Execute and the Media will be shared (Figure 4). Click Execute to create the job and run it.

Figure 4. Updating the environment and executing the job
A pixel ruler showing the maximum width of an image used for an article (580 pixels)

When the job begins executing, the process will be displayed. View the status of the executing jobs from the Jobs navigation item. The status of each step will be displayed as the steps are executed (Figure 5).

Figure 5. Viewing the job step status and results
A pixel ruler showing the maximum width of an image used for an article (580 pixels)

The display will automatically be updated for a predefined amount of time (but not indefinitely) that is configured in the system properties. The indication that the status is not being updated anymore is when the progress indicator in the right upper corner of the display has stopped (Figure 6). Click on the circle once and the status will continune updating.

Figure 6. Automatic result update indicator
A pixel ruler showing the maximum width of an image used for an article (580 pixels)

Depending on the job, data, and other factors, some steps of the job will run, some will be skipped, and some will fail but continue. All these results are acceptable in this project but when a step fails, investigate the problem using the method below.

Failure investigation

When a failure occurs in a job, the job page will indicate the job has completed with a failed state. When you select the job name, the job steps will be displayed. The result of the failed step will be indicated with a red cross. You should select the step name to view the detail output of the selected step.

Figure 7. Job step failure
A pixel ruler showing the maximum width of an image used for an article (580 pixels)

The job details are based on the output of the selected step and can consist of a variable amount of information. Rational Application Framework will indicate where the failure occurred in the process of executing the command. The error message will usually be printed before the BUILD FAILED message (Figure 8).

Figure 8. Job step output
A pixel ruler showing the maximum width of an image used for an article (580 pixels)

When a failure is corrected, the job can be restarted. The restart action will run the job steps from where it failed.

Post installation steps

The project that installed the products and created the cell will also start the deployment manager, node agents, and IBM HTTP Server. The cell would need to be stopped and the chown command would need to be executed on the newly created folders on each of the target systems to change the ownership of the WebSphere Application Server installation folders. When the ownership is changed on the targets, Rational Application Framework should also change to now access WebSphere Application Server with the process owner ID instead of root. This can be accomplished by modifying the RAF_HOME/user/environments/[ENVIRONMENT NAME]/cells/[CELL NAME]/ file.

Modify the values in the file with those shown in Listing 3 to represent the WebSphere Application Server process owner ID. Enter the password in clear text; Rational Application Framework will encrypt the password the next time the file is read.

Update the target user
# Used for connectivity and to chown install over to right user/group


Automation is not a new concept when it comes to WebSphere Application Server or system administration. Administrators have used scripts for many years to create and administer WebSphere environments. Rational Automation Framework is providing a solid foundation for executing administrative scripts by leveraging Build Forge to execute the scripts and monitor the results. Build Forge provides the benefits to schedule jobs and store the results of jobs for further analysis and auditing. Rational Application Framework provides the mechanism to externalize environmental values for ease of reuse. Combined, the product provides the power and flexibility to automate the administration of WebSphere products in large enterprises.

The process of distributing the software and installing WebSphere software is only the start of the rich capabilities that Rational Application Framework provide. Rational Application Framework comes with many predefined actions to manage your environments on a daily basis, as well as provide you the capabilities to extend and customize actions that are specific to your needs.



developerWorks: Sign in

Required fields are indicated with an asterisk (*).

Need an IBM ID?
Forgot your IBM ID?

Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name

The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.


All information submitted is secure.

Dig deeper into WebSphere on developerWorks

Zone=WebSphere, Rational
ArticleTitle=Deploying WebSphere software with Rational Automation Framework