The Support Authority: Manage your WebSphere product installations, configurations, and application deployments with Rational Automation Framework for WebSphere

IBM® Rational® Automation Framework for WebSphere® is a product for managing IBM WebSphere product installations, configurations, and application deployments. It provides the ability to easily move resource configurations and applications along the stages of the development lifecycle to help you can gain control of your existing WebSphere product environments. This content is part of the IBM WebSphere Developer Technical Journal.


Tim Robertson (, Software Engineer, IBM

Tim Robertson is a software engineer developing the IBM Rational Automation Framework for WebSphere in Austin, TX. In his career at IBM he has also worked on the IBM Rational Build Forge product, as well as z/OS problem determination tools, languages, and CICS.

Dr. Mahesh Rathi (, WebSphere Application Server SWAT Team, IBM

Dr. Mahesh Rathi has been involved with WebSphere Application Server product since its inception. He led the security development team before joining the L2 Support team, and joined the SWAT team in 2005. He thoroughly enjoys working with demanding customers, on hot issues, and thrives in pressure situations. He received his PhD in Computer Sciences from Purdue University and taught Software Engineering at Wichita State University before joining IBM.

14 July 2010

Also available in Chinese Russian

In each column, The Support Authority discusses resources, tools, and other elements of IBM® Technical Support that are available for WebSphere® products, plus techniques and new ideas that can further enhance your IBM support experience.

This just in...

As always, we begin with some new items of interest for the WebSphere community at large:

Continue to monitor the various support-related Web sites, as well as this column, for news about other tools as we encounter them.

And now, on to our main topic...

Managing existing environments with Rational Automation Framework for WebSphere

This article applies to IBM Rational Automation Framework for WebSphere V7.1.1.4. Some of the features described here are not available in earlier versions.

IBM Rational Automation Framework for WebSphere (hereafter referred to as Rational Automation Framework) is a solution for managing the installation, configuration, and application deployments for IBM WebSphere products. Rational Automation Framework is data driven to provide accuracy and consistency, as well as increased speed in the form of parallel execution -- beyond the performance gains acquired through automation.

The framework ships with over 500 actions, which are granular building blocks used to build an automation solution for your WebSphere products. Rational Automation Framework is built on top of a proven, enterprise level automation platform in the form of IBM Rational Build Forge, and currently supports WebSphere Application Server V6.0, 6.1 and 7.0, WebSphere Portal V6.0 and 6.1, and IBM HTTP Server V6.0, 6.1 and 7.0. Additionally the Rational Automation Framework team has provided incubator code for IBM WebSphere Virtual Enterprise and the IBM WebSphere Business Process Management suite, including IBM WebSphere Process Server, IBM WebSphere Enterprise Service Bus, IBM WebSphere Business Monitor, and IBM WebSphere Service Registry and Repository.

Rational Automation Framework for WebSphere and Rational Build Forge enable you to manage your IBM WebSphere product cells. Rational Automation Framework provides two options for bringing a cell under the management of the framework:

  • The first is to use the new cell wizard to define the topology of a new WebSphere product cell. After running through the new cell wizard, an automation plan will be created to install the WebSphere product bits, create and federate the profiles, install IBM HTTP Server, install the plug-in, and so on.
  • The other option is to import an existing WebSphere product cell into Rational Automation Framework. Using the existing cell wizard, you simply specify a minimal set of information about the existing cell, such as the host name of one of the nodes, credentials for the operating system and WebSphere product user, and a profile location. Rational Automation Framework will then discover the cell's topology and then build a representation in Rational Automation Framework and an automation plan to import configuration data from the cell (Figure 1).
Figure 1. Example run of the Rational Automation Framework existing cell wizard
Figure 1. Example run of the Rational Automation Framework existing cell wizard

After importing the cell's topology into Rational Automation Framework, an automation plan is created that will run the action was_common_configure_all at all applicable scopes. This will import nearly all of the configuration of the existing cell. The example environment described here is a WebSphere Application Server Network Deployment environment, and so the automation plan will run the import all action at the cell, clusters, nodes, and servers scope (Figure 2).

Figure 2. Automation plan to import the cell's configuration
Figure 2. Automation plan to import the cell's configuration

Capturing the configuration

Rational Automation Framework supports several modes of operation. These modes vary action by action, but many of the actions support Import mode. Because Rational Automation Framework actions are designed to handle a specific portion of the configuration, you can use an action to pinpoint exactly what you'd like to capture.

For example, you could run the was_common_configure_jdbc_providers actions in Import mode at cell scope to import just data providers that are defined at the cell scope into Rational Automation Framework. The data is then stored in a normalized, version-agnostic XML format on the Rational Automation Framework server. These documents can then be version controlled. Unlike the application server, where many resource types are stored in a single XML file, Rational Automation Framework stores related resources in their own XML files. For examples, data sources, JDBC providers, and was40 data sources are all stored in the jdbc.xml file. Additionally, there is a jdbc.xml file created at each scope where a corresponding Import mode command was run.

Suppose you have a TEST_PROMOTE environment defined. You could run this command:

rafw_home\bin\rafw.bat -env TEST_PROMOTE -cell qa -cluster cluster1 -import was_common_configure_jdbc_providers

After completion of this command, the file rafw_home/user/environments/TEST_PROMOTE/cells/qa/clusters/cluster1/jdbc.xml will contain definitions of all the JDBC providers defined at the cluster1 scope (Listing 1).

Listing 1. Example output of Import mode run at a scope with one JDBC provider defined
<?xml version="1.0"?>

        description="XA DB2 Universal JDBC Driver-compliant Provider. Datasources 
created under this provider support the use of XA to perform 2-phase commit processing. 
Use of driver type 2 on WebSphere Application Server for Z/OS is not supported for 
datasources created under this provider."
        name="DB2 Universal JDBC Driver Provider (XA)"
        providerType="DB2 Universal JDBC Driver Provider (XA)"


In this case, only a single JDBC provider existed at the cluster1 scope.

Applying Rational Automation Framework’s repository configuration to a cell

After capturing configuration information in Rational Automation Framework, you can now playback the configuration data in Rational Automation Framework using the same action in Execute mode. Execute mode will first delete all configuration elements of the given type and then recreate them based on the information stored in the Rational Automation Framework configuration repository. Notice that each of the existing data sources being removed from the WebSphere Application Server configuration are being created based on the model in the Rational Automation Framework configuration repository.

Adding resources to the configuration

Augment mode in Rational Automation Framework enables you to add configuration elements to a WebSphere Application Server cell. Augment mode is truly additive and will not update existing configuration elements. A check will be made to determine if a specified configuration element exists; if it does, a warning message will be displayed and the element will be skipped. Definitions for resources to be augmented are specified in a file named <type>_augment.xml; for example, jdbc_augment.xml for JDBC related resources. Figure 3 illustrates the warning messages for existing resources as well as the addition of new resources to the WebSphere Application Server configuration.

Figure 3. Augment mode action flagging existing elements that will be skipped and new resources added
Figure 3. Augment mode action flagging existing elements that will be skipped and new resources added

Comparing Rational Automation Framework’s repository with a live cell

"Configuration drift" refers to a situation that can occur when over time differences are introduced into a WebSphere product environment. While most users diligently attempt to keep their staging and production environments in sync, inevitably a change is introduced that ultimately goes unnoticed. A common source of such rogue changes are attempts to debug an issue in production. When a critical application is down at 2:00 AM, it is possible that not all changes made while attempting to bring the application back online are documented – or reverted if not required. In the short term, the changes in these applications might seem harmless, but once you deploy a new application it begins to behave differently in your production versus staging environments. Or possibly there is a difference between your east and west coast data centers. Change made in the "heat of battle" might seem innocuous at first, but when it begins to cause problems you are left to find the needle in a haystack.

Compare mode in Rational Automation Framework will compare the configuration stored in Rational Automation Framework's repository with the corresponding configuration in the live cell and flag any differences. Using the Rational Build Forge automation platform, you can schedule these comparisons during off-peak hours and run them on a regular basis. If a change is caught early, it is much easier to make an informed decision on whether or not the change should be accepted or reverted, rather than trying to recall why a change was made six months ago.

Figure 4 shows the results of a comparison where the Rational Automation Framework configuration contains a data source resource that doesn't exist in the WebSphere product cell.

Figure 4. Comparison mode flagging a missing object in the live cell
Figure 4. Comparison mode flagging a missing object in the live cell

Figure 5 shows an example of a comparison that flagged a change to the max connections setting on the connection pool attribute of a data source.

Figure 5. Change to an attribute on a data source
Figure 5. Change to an attribute on a data source

Once a difference is flagged in Rational Automation Framework's Compare mode, you have the choice of keeping the change and updating the Rational Automation Framework repository with the new value. This is accomplished by running the corresponding Rational Automation Framework action in import mode. If you decide to not keep the change, you can reapply the configuration stored in Rational Automation Framework by running the corresponding action in execute mode. This will recreate the configuration according to the values saved in Rational Automation Framework.

Deploying enterprise applications

Rational Automation Framework uses a properties file that describes the enterprise application deployment options and indicates the location of the .ear file to be deployed. The action was_common_deploy_install_app -a <app name> is used to deploy EAR files. The application properties file can be in one of two formats:

  • The first format is a single OPTIONS key that contains all of the wsadmin options for the deployment. This option string can be rapidly created using most versions of WebSphere Application Server by simply using the admin console to deploy the application and selecting the View Administration scripting command for last action link.
  • The other option for creating these properties files is to create each option in wsadmin as its own key in the file. This approach enables administrators to create a template version of the file they can pass to developers. Developers then only have to worry about a small set of options. Listing 2 shows a segment from one of these files. In this example, the developers will determine whether the preCompileJSPs option should be used, but the administrators will decide which servers the modules are mapped to. Rational Automation Framework ships with example files for each version of WebSphere Application Server that is supported by the framework.
Listing 2
# Precompile JavaServer Pages files

# Distribute application

# The MapModulesToServers option specifies the application server where
# you want to install modules that are contained in your application.["Default Application" default_app.war,
WEB-INF/web.xml WebSphere:cell=mycell,node=mynode,server=server1]
options.multi.two.MapModulesToServers=["Default Application" default_app.war,
WEB-INF/web.xml WebSphere:cell=mycell,node=mynode,server=server2
options.multi.three.MapModulesToServers=["Examples Application" examples.war,
WEB-INF/web.xml WebSphere:cell=mycell,node=mynode,server=server2+WebSphere:cell=mycell,

Promoting resources along the development lifecycle

As an application and its configuration changes move along the development lifecycle, great care must be taken to move the related resources from one stage to the next; for example, moving data sources required by a new application from the shared test environment into the staging environment. While it's desirable to keep almost all of the data the same (such as the database and JNDI names), there are other values that should change from one environment to another. You wouldn't want your data sources pointing to your production database server.

Rational Automation Framework's Promote mode was designed to handle this specific challenge. Promote mode acts as a pull operation, and will pull the configuration from one Rational Automation Framework environment into another. In practical terms, this means you would pull the configuration from the shared test environment into staging. However, bi-directional promotion is supported. This is useful if you find a problem in your production environment and want to promote that same configuration to your test environment to try and debug the issue. Additionally, you are able to change scope during promotion. For example, if a developer is working in a standalone single server environment and creates his data sources at the server scope, then during promotion into the Network Deployment clustered shared test environment the data sources can be moved to the cluster scope. In order to handle known environmental differences, Rational Automation Framework passes promoted data through a filter. The filter understands two types of expressions:

  • The first is a simple text-based replacement. In order for the text-base replacement to be enabled, a file is required at both the promoted from and to scopes. The files must contain the same keys. In the standalone server to Network Deployment cluster promotion example above, the keys in each file would be:
    • Standalone environment at the server scope: myKey=ABC
    • Network Deployment environment at the cluster scope: myKey=XYZ
    When the promote mode action is run, it will find the matching keys and change all occurrences of "ABC" to "XYZ." This approach is powerful, but doesn't enable fine-grained control.
  • The other type of filter is based on Xpath expressions. Much like SQL for relational databases, Xpath enables you to navigate to various places in an XML document. For Xpath keys, you only need to specify the key and value in the target environment’s file. There will be two keys, one with the .xpath suffix that contains the Xpath expression, and one with a .value suffix that represents the new value. In the example shown in Listing 3, the Xpath expression indicates that for all JavaProcessDef elements, get the maximumHeapSize attribute of the JavaVirtualMachine element. Once you locate the attribute, set the value to 512. In WebSphere Application Server terms, you are enforcing the MaximumHeapSize for each of your server JVMs to be 512MB. A developer might have been testing with a 2GB maximum heap size on his local desktop, but the same configuration isn't realistic on a shared server hosting numerous JVMs.
    Listing 3

    Another example would be to change a widgetDB Data Source to point to the production database server and use a port 5001.

    Listing 4


IBM Rational Automation Framework for WebSphere is a field-proven product used to manage IBM WebSphere product installations, configurations, and application deployments. Leveraging the core enterprise automation platform in IBM Rational Build Forge, you can use Rational Automation Framework to create a repeatable, accurate, and fast automation infrastructure suited to your WebSphere product environments. With more than 500 actions and more than 30 automation libraries (and counting), Rational Automation Framework offers a huge array of possibilities for managing your WebSphere Application Server environments out of the box. The underlying automation platform and Rational Automation Framework itself offer much in the way of extensibility for those already invested in WebSphere Application Server scripting.



Get products and technologies



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 Business process management on developerWorks

Zone=Business process management, WebSphere, Rational
ArticleTitle=The Support Authority: Manage your WebSphere product installations, configurations, and application deployments with Rational Automation Framework for WebSphere