• Introduction
• Requirements
• Before you get started
• Overview of WebSphere Application Server configuration management with IBM UrbanCode Deploy
• Create the resource tree
• Discover and templatize cell configuration data
• Discover and templatize node configuration data
• Discover and templatize server configuration data
• Discover and templatize a node with all servers
• Discover and templatize cluster configuration data
• Discover and templatize a cell, including all clusters
• Add components to the resource tree
• Set up an application in IBM UrbanCode Deploy
• Apply configuration changes to the target WebSphere Application Server environment
• Troubleshooting

Introduction

You can use IBM® UrbanCode™ Deploy (now IBM DevOps Deploy) and the IBM WebSphere® Application Server – Configure plug-in to manage WebSphere configurations. The IBM WebSphere Application Server – Configure plug-in stores WebSphere configuration data as a series of templates. In a DevOps scenario, these templates are not only used to track and manage configuration changes, but also to promote WebSphere Application Server configurations among environments. For example, a WebSphere Application Server configuration might be finalized in a development environment, then applied to a QA environment for testing, and then applied to the production environment.

Similarly, IBM UrbanCode Deploy and the WebSphere Application Server – Configure plug-in can be used to collect the configuration of a WebSphere Application Server v7 or v8 environment, convert it into templates, and then apply the configuration to an environment that is running a later version of WebSphere Application Server. This document describes that approach.

For more information, see this short video or this detailed video.

Benefits of migrating using IBM UrbanCode Deploy

• Keep your current WebSphere Application Server environment running.
• Perform WebSphere Application Server migration in a timely manner.
• After migration, use IBM UrbanCode Deploy to manage WebSphere Application Server configurations in a DevOps scenario. Using this management approach includes these benefits:
  • Easily promote WebSphere Application Server configurations among environments.
  • Add, modify, and remove individual configuration objects by manipulating templates.
  • Apply configuration changes at specific scopes (cell, node, server, cluster).
  • Trace configuration changes and put configuration data under version control.
  • Compare versions of WebSphere Application Server configuration data to detect differences.
  • Compare WebSphere Application Server configuration data in IBM UrbanCode Deploy to a live WebSphere Application Server environment to detect differences.
  • Use permissions to control who can change WebSphere Application Server configurations.

Requirements

• IBM UrbanCode Deploy version 6.2 or later. For best results, use version 6.2.0.2 or later.
• WebSphere Application Server – Configure plug-in version 33 or later.
• WebSphere Application Server – Deployment version 92 or later.
• For environments that use dynamic clusters, upgrade the target environment to WebSphere Application Server 8.5.5.7 or later.

Before you begin

Read this entire document before you plan your migration.

Although the WebSphere Application Server Configure plug-in can migrate configuration information from one version of WebSphere Application Server to another, it does not copy or move additional files from one environment to another. Some files in your source WebSphere Application Server environment might need to be manually copied to and installed in your target WebSphere Application Server environment. For example, you must manually copy files in the following situations:

• If SSL is enabled between WebSphere Application Server and an LDAP server, the root certificate from the LDAP server must be manually installed on the target WebSphere Application Server environment before you attempt migration.
• If your environment includes resource adapters, all resource adapters (.rar files) must be manually installed on the target WebSphere Application Server environment.

Configuration data can contain file system paths. For example, node configuration data might contain the file system path to the installation directory for the Java virtual machine. If these paths are different in the source and target environments, you must update the configuration data. For example, if the file system path to the Java virtual machine is ${WAS_INSTALL_ROOT}/java in the source environment, but the file system path to the Java virtual machine in your target environment is ${WAS_INSTALL_ROOT}/new/java, the configuration data must be updated to use the ${WAS_INSTALL_ROOT}/new/java value. You can use the User Defined Tokenization field of the templatize steps to update these values. See the Discover and Templatize sections of this document for more information on using the User Defined Tokenization field.

Overview of WebSphere Application Server configuration management with IBM UrbanCode Deploy

For more information, see the WebSphere Application Server – Configure plug-in page for more detailed documentation and examples.

The WebSphere Application Server – Deployment plug-in is used to discover the topology of a WebSphere Application Server environment. After the discovery process, the UrbanCode Deploy resource tree displays the cell, nodes, servers, and clusters of your WebSphere Application Server environment, as shown in the following example screen capture:

WebSphere configuration data is stored in UrbanCode Deploy components. The configuration data is stored as one or more JSON files, which represent WebSphere cells, nodes, servers, and clusters. Each WebSphere object is represented by a component. For example, the following screen capture shows a component that contains configuration data for a server:

After components are created and contain configuration data for the cell, nodes, servers, and clusters, the components are placed in the resource tree under the resource role that they manage. For example, a component that is used to manage ServerXYZ is placed directly under ServerXYZ in the resource tree.

Configuration data that is stored in components can then be applied to the resource that they are associated with in the resource tree. For example, applying the Server - server1 component in the previous screen capture would update the configuration of the server that is named server1 in the target environment.

Overview of the migration process

The migration process follows three high-level steps:

1. Discover WebSphere Application Server configuration data from the source WebSphere Application Server environment.
2. Convert the discovered WebSphere Application Server configuration data into templates that can be applied to any environment.
3. Apply the configuration data templates to your target environment.

Create the resource tree

1. Install the IBM UrbanCode Deploy agent on the Deployment Manager in the source WebSphere Application Server environment.
2. On the Resources page in IBM UrbanCode Deploy, click Create Top-Level Group, and then specify a group name, and click Save.
3. For the new top-level group, click Actions > Add Agent, and then select the agent that you installed on the source WebSphere Application Server environment.
4. Click Refresh until a resource that represents your WebSphere Application Server cell is displayed in the resource tree.
5. For the cell resource, click Edit (the pencil icon), and then enter your WebSphere user name, password, and connection information (including port number). This information specifies how the UrbanCode Deploy agent connects to WebSphere Application Server to run wsadmin commands. Click Save.
6. For the cell resource, click Actions > Configure using WebSphere Topology Discovery.
7. After topology discovery is complete, close the window, and refresh the resource tree. Nodes, servers, and clusters in your source WebSphere Application Server environment are displayed in the resource tree.
8. Repeat all the previous steps for the target WebSphere Application Server environment.
9. Manually copy and install any required files from the source WebSphere Application Server environment to the target WebSphere Application Server environment, as described in the Before you get started section of this document.

Discover and templatize cell configuration data

Complete the following steps to extract configuration data at the cell scope from your source WebSphere Application Server environment and convert it into a template that can later be applied to your target WebSphere Application Server environment.

1. From the IBM WebSphere Application Server – Configure plug-in page, download the WebSphere – Example 8 – Discover & Templatize Cell Configuration Data example process, and then import the process into UrbanCode Deploy.
2. On the Processes page, click Run for the process.
3. In the Run Process window, enter the following values in the fields:
   1. For Config File, enter the location and name of the initial configuration file to create. To save the configuration file in the working directory on the agent computer, leave the default value.
   2. For Output Directory, enter the location and name of the directory to use to store the templatized configuration data. To store the template in the working directory, leave the default value.
   3. For User Defined Tokenization, specify values to update, or tokenize, in the configuration data. Put each entry on a separate line. Use the following format: oldValue->newValue. For example, if there is an LDAP server that is named ldapServerABC in your source WebSphere Application Server configuration data, and an LDAP server that is named ldapServerXYZ on your target WebSphere Application Server environment, enter ldapServerABC->ldapServerXYZ in this field. When the process runs, every instance of the text ldapServerABC in cell configuration data is replaced by ldapServerXYZ.
      Important: If variables such as INSTALL_ROOT or PROFILE_ROOT are different in the source and target WebSphere Application Server environments, you must update the configuration data with the correct values for the target environment.
      If you are migrating from WebSphere Application Server 7, use this field to update the location of the built-in WebSphere MQ resource adapter. In version 7, this adapter is located at {CONNECTOR_INSTALL_ROOT}/wmq.jmsra.rar. In version 8 and later, this adapter is located at {WAS_INSTALL_ROOT}/installedConnectors/wmq.jmsra.rar. You must update version 7 configuration data to the new value if you are migrating to version 8 or later. In the User Defined Tokenization field, enter the following line:
      ${CONNECTOR_INSTALL_ROOT}->${WAS_INSTALL_ROOT}/installedConnectors
   4. For Resource, click Set, and then select the cell resource of the source environment.
4. Click Submit to run the process.
5. After the process is complete, verify that a component was created in this format: Cell – cell name. Go to the Components page. Click the name of the new component, click the Versions tab, click the version, and then verify that the configuration data exists as a component version artifact.
   
6. Edit the component’s Apply process. View the properties of the Apply Config step. Check the Show Hidden Properties checkbox, then ensure the Only Update/Create Configuration Objects checkbox is checked. If it is not checked, configuration objects that exist in your target environment but do not exist in your source environment may be deleted.

Discover and templatize node configuration data

Complete the following steps to pull configuration data at the node scope from your source WebSphere Application Server environment and convert it into a template that can later be applied to your target WebSphere Application Server environment.

1. From the IBM WebSphere Application Server – Configure plug-in page, download the WebSphere – Example 9 – Discover & Templatize Node Configuration Data example process, and then import the process into UrbanCode Deploy.
2. On the Processes page, click Run for the process.
3. In the Run Process window, enter the following values in the fields:
   1. For Config File, enter the location and name of the initial configuration file to create. To save the configuration file in the working directory on the agent computer, leave the default value.
   2. For Output Directory, enter the location and name of the directory to use to store the templatized configuration data. To store the template in the working directory, leave the default value.
   3. For User Defined Tokenization, specify values to update, or tokenize, in the configuration data. Put each entry on a separate line. Use the following format: oldValue->newValue. When the process runs, every instance of oldValue in your node configuration data is replaced by newValue.
      Important: If variables such as INSTALL_ROOT or PROFILE_ROOT are different in the source and target WebSphere Application Server environments, you must update the configuration data with the correct values for the target environment. For example, if your source WebSphere Application Server environment was installed in /opt/IBM/WebSphere7/AppServer and your target WebSphere Application Server environment was installed in /opt/someDirectory/WebSphere/AppServer, the configuration data must be updated to replace /opt/IBM/WebSphere7/ with /opt/someDirectory/WebSphere/AppServer. Use the User Defined Tokenization field to update these values. For example, enter /opt/IBM/WebSphere7/->/opt/someDirectory/WebSphere/AppServer to replace the values in your configuration data.
   4. For Resource, click Set, and then select the node resource of the source environment to base your template on.
4. Click Submit to run the process.
5. After the process is complete, verify that a component was created in this format: Node – node name. Go to the Components page. Click the name of the new component, click the Versions tab, click the version, and then verify that the configuration data exists as a component version artifact.
6. If your WebSphere Application Server environment contains more than one node, repeat steps 2 – 5 for any nodes in the environment that do not share the configuration with the new component and template. If the node configuration is the same for all nodes in your environment, you do not have to templatize all nodes.
   
7. Edit the component’s Apply process. View the properties of the Apply Config step. Check the Show Hidden Properties checkbox, then ensure the Only Update/Create Configuration Objects checkbox is checked. If it is not checked, configuration objects that exist in your target environment but do not exist in your source environment may be deleted.

Discover and templatize server configuration data

Complete the following steps to extract configuration data at the server scope from your source WebSphere Application Server environment and convert it into a template that can later be applied to your target WebSphere Application Server environment.
Note: For dynamic clusters, you do not need to templatize or manage dynamic cluster member servers. They are created and managed by the dynamic cluster and the dynamic cluster server template.

When you complete the following steps, make sure to discover and templatize any Deployment Manager or node agent servers.

1. From the IBM WebSphere Application Server – Configure plug-in page, download the WebSphere – Example 10 – Discover & Templatize Server Configuration Data example process, and then import the process into UrbanCode Deploy.
2. On the Processes page, click Run for the process.
3. In the Run Process window, enter the following values in the fields:
   1. For Config File, enter the location and name of the initial configuration file to create. To save the configuration file in the working directory on the agent computer, leave the default value.
   2. For Output Directory, enter the location and name of the directory to use to store the templatized configuration data. To store the template in the working directory, leave the default value.
   3. For User Defined Tokenization, specify values to update, or tokenize, in the configuration data. Put each entry on a separate line. Use the following format: oldValue->newValue. When the process runs, every instance of oldValue in your server configuration data is replaced by newValue.
      Important: If variables such as INSTALL_ROOT or PROFILE_ROOT are different in the source and target WebSphere Application Server environments, you must update the configuration data with the correct values for the target environment. For example, if your source WebSphere Application Server environment was installed in /opt/IBM/WebSphere7/AppServer and your target WebSphere Application Server environment was installed in /opt/someDirectory/WebSphere/AppServer, the configuration data must be updated to replace /opt/IBM/WebSphere7/ with /opt/someDirectory/WebSphere/AppServer. Use the User Defined Tokenization field to update these values. For example, you can enter /opt/IBM/WebSphere7/->/opt/someDirectory/WebSphere/AppServer and the values will be replaced in your configuration data.
   4. For Node Host Name, enter the host name of the node that contains the server to templatize.
   5. For Resource, click Set, and then select the server resource of the source environment to base your template on.
4. Click Submit to run the process.
5. After the process is complete, verify that a component was created in this format: Server – server name. Go to the Components page. Click the name of the new component, click the Versions tab, click the version, and then verify that the configuration data exists as a component version artifact.
   
6. If your WebSphere Application Server environment contains more than one server, repeat steps 2 – 5 for any servers in the environment that do not share the configuration with the new component and template. If the server configuration is the same for all servers in your environment, you do not have to templatize all servers.
7. Edit the component’s Apply process. View the properties of the Apply Config step. Check the Show Hidden Properties checkbox, then ensure the Only Update/Create Configuration Objects checkbox is checked. If it is not checked, configuration objects that exist in your target environment but do not exist in your source environment may be deleted.

Discover and templatize a node with all servers

The previous section describes how to templatize a node and individual servers. In the previous scenario, a component might be created for each node and for each server.

The individual server approach can work well in a DevOps environment, where you manage each node or server with a component in UrbanCode Deploy. For example, if configuration updates must be made to ServerABC in your target environment, changes to only ServerABC can be applied. Likewise, if ServerABC is in a development environment and is ready to be promoted to a test environment, it is easy to promote only ServerABC.

In a migration scenario, it might take a long time to discover and templatize each server individually. For example, if your node contains 100 servers, and each server has a unique configuration, you might not want to templatize 100 servers, one at a time. In this case, you can discover and templatize a node and all of the servers in the node at once and store all the configuration data in one component.

Complete the following steps to retrieve configuration data for a node and all servers in the node from your source WebSphere Application Server environment and convert it into a template that can later be applied to your target WebSphere Application Server environment.

If you use this approach, keep the following items in mind:

• All configuration data for a node and all servers in the node is stored in a single component.
• Because all configuration data for a node and a number of servers is stored in a single component, managing configuration data in a DevOps scenario might become challenging. For example, to make a change to ServerABC, configuration data for the node and all servers will be reapplied, which might take a long time if the node contains many servers.
• Server names are hardcoded in the configuration data. To alter server names when the configuration data is templatized, use the User Defined Tokenization field when you run the process.
• Dynamic cluster member servers do not have to be templatized because dynamic clusters and the dynamic cluster server template manage the creation and update of these servers. If your node contains dynamic cluster member servers, you might not want to use this approach, because this approach includes configuration data for all of the dynamic cluster member servers.

To discover and templatize a node with all servers:

1. From the IBM WebSphere Application Server – Configure plug-in page, download the WebSphere – Example 9 – Discover & Templatize Node Configuration Data example process, and import the process into UrbanCode Deploy.
2. Click the process name, and then click Design to open the process editor.
3. Click Edit (the pencil icon) on the WebSphere Configuration Discovery step.
4. Select Show Hidden Properties.
5. In the Limit Discovery Scope list, select None.
6. Click OK, and then click Save.
7. On the Processes page, click Run for the process.
8. In the Run Process window, enter the following values in the fields:
   1. For Config File, enter the location and name of the initial configuration file to create. To save the configuration file in the working directory on the agent computer, leave the default value.
   2. For Output Directory, enter the location and name of the directory to use to store the templatized configuration data. To store the template in the working directory, leave the default value.
   3. For User Defined Tokenization, specify values to update, or tokenize, in the configuration data. Put each entry on a separate line. Use the following format: oldValue->newValue. When the process runs, every instance of oldValue in your node configuration data is replaced by newValue.
      Important: If variables such as INSTALL_ROOT or PROFILE_ROOT are different in the source and target WebSphere Application Server environments, you must update the configuration data with the correct values for the target environment. For example, if your source WebSphere Application Server environment was installed in /opt/IBM/WebSphere7/AppServer and your target WebSphere Application Server environment was installed in /opt/someDirectory/WebSphere/AppServer, the configuration data must be updated to replace /opt/IBM/WebSphere7/ with /opt/someDirectory/WebSphere/AppServer. Use the User Defined Tokenization field to update these values. For example, you can enter /opt/IBM/WebSphere7/->/opt/someDirectory/WebSphere/AppServer and the values will be replaced in your configuration data.
   4. For Resource, click Set, and then select the node resource of the source environment to base your template on.
9. Click Submit to run the process.
10. After the process is complete, verify that a component was created in this format: Node – node name. Go to the Components page. Click the name of the new component, click the Versions tab, click the version, and then verify that the configuration data exists as a component version artifact.
    
11. Edit the component’s Apply process. View the properties of the Apply Config step. Check the Show Hidden Properties checkbox, then ensure the Only Update/Create Configuration Objects checkbox is checked. If it is not checked, configuration objects that exist in your target environment but do not exist in your source environment may be deleted.

Discover and templatize cluster configuration data

Complete the following steps to extract configuration data at the cluster scope from your source WebSphere Application Server environment and convert it into a template that can later be applied to your target WebSphere Application Server environment. For static clusters, individual cluster members must be managed by a server component that contains server configuration data. For dynamic clusters, a server template is included with the dynamic cluster configuration data and the dynamic cluster uses that template to create and manage cluster members.

1. From the IBM WebSphere Application Server – Configure plug-in page, download the WebSphere – Example 11 – Discover & Templatize Cluster Configuration Data example process, and then import the process into UrbanCode Deploy.
2. On the Processes page, click Run for the process.
3. In the Run Process window, enter the following values in the fields:
   1. For Config File, enter the location and name of the initial configuration file to create. To save the configuration file in the working directory on the agent computer, leave the default value.
   2. For Output Directory, enter the location and name of the directory to use to store the templatized configuration data. To store the template in the working directory, leave the default value.
   3. For User Defined Tokenization, specify values to update, or tokenize, in the configuration data. Put each entry on a separate line. Use the following format: oldValue->newValue. When the process runs, every instance of oldValue in your cluster configuration data is replaced by newValue.
      Important: If variables such as INSTALL_ROOT or PROFILE_ROOT are different in the source and target WebSphere Application Server environments, you must update the configuration data with the correct values for the target environment. For example, if your source WebSphere Application Server environment was installed in /opt/IBM/WebSphere7/AppServer and your target WebSphere Application Server environment was installed in /opt/someDirectory/WebSphere/AppServer, the configuration data must be updated to replace /opt/IBM/WebSphere7/ with /opt/someDirectory/WebSphere/AppServer. Use the User Defined Tokenization field to update these values. For example, you can enter /opt/IBM/WebSphere7/->/opt/someDirectory/WebSphere/AppServer and the values will be replaced in your configuration data.
   4. For Resource, click Set, and then select the cluster resource of the source environment to base your template on.
4. Click Submit to run the process.
5. After the process is complete, verify that a component was created in this format: Cluster – cluster name. Go to the Components page. Click the name of the new component, click the Versions tab, click the version, and then verify that the configuration data exists as a component version artifact.
   
6. If your WebSphere Application Server environment contains more than one cluster, repeat steps 2 – 5 for any clusters in the environment that do not share the configuration with the new component and template. If the cluster configuration is the same for all clusters in your environment, you do not have to templatize all clusters.
7. Edit the component’s Apply process. View the properties of the Apply Config step. Check the Show Hidden Properties checkbox, then ensure the Only Update/Create Configuration Objects checkbox is checked. If it is not checked, configuration objects that exist in your target environment but do not exist in your source environment may be deleted.

Special considerations for static clusters

For static clusters, individual cluster members must be managed by a server component that contains server configuration data. However, cluster members are also listed in the configuration data for the cluster. To add or remove cluster members, you must edit the cluster configuration data. Cluster members are listed under the Cluster Members path. The following code shows an example of how two cluster members are represented in cluster configuration data. Ensure that the cluster member names and the node name match the values in your target environment.

{
        "description": "Discovered Cluster Members",
        "inheritTeam": "true",
        "name": "Cluster Members",
        "path": "/@websphere.cell@/ServerClusters/@websphere.cluster@/Cluster Members",
        "teamMappings": []
    },
    {
        "description": "Discovered WebSphereClusterMember",
        "inheritTeam": "true",
        "name": "JWC-CustomNode01Node01-amatthewMember1",
        "path": "/@websphere.cell@/ServerClusters/@websphere.cluster@/Cluster Members/JWC-CustomNode01Node01-amatthewMember1",
        "roleName": "WebSphereClusterMember",
        "roleProperties": {
            "websphere.clustermember.membername": "amatthewMember1",
            "websphere.clustermember.nodename": "JWC-CustomNode01Node01",
            "websphere.clustermember.weight": "2"
        },
        "teamMappings": []
    },
    {
        "description": "Discovered WebSphereClusterMember",
        "inheritTeam": "true",
        "name": "JWC-CustomNode01Node01-amatthewMember2",
        "path": "/@websphere.cell@/ServerClusters/@websphere.cluster@/Cluster Members/JWC-CustomNode01Node01-amatthewMember2",
        "roleName": "WebSphereClusterMember",
        "roleProperties": {
            "websphere.clustermember.membername": "amatthewMember2",
            "websphere.clustermember.nodename": "JWC-CustomNode01Node01",
            "websphere.clustermember.weight": "2"
        },
        "teamMappings": []
    }

Note: When you apply configuration changes that are related to static clusters, remember that cluster members must exist on the target environment before you apply cluster configuration data. In other words, apply the server (cluster member) configuration data first, and then apply the cluster configuration data.

Discover and templatize a cell, including all clusters

The previous section describes how to templatize an individual cluster. In the previous scenario, a component is created for each cluster.

The individual cluster approach can work well in a DevOps environment, where you manage each cluster with a component in UrbanCode Deploy. For example, if configuration updates must be made to ClusterABC in your target environment, changes to only ClusterABC can be applied. Likewise, if ClusterABC is in a development environment and is ready to be promoted to a test environment, it is easy to promote only ClusterABC.

In a migration scenario, it might take a long time to discover and templatize each cluster individually. For example, if your cell contains 100 clusters, and each cluster has a unique configuration, you might not want to templatize 100 clusters, one at a time. In this case, you can discover and templatize a cell and all the clusters in the cell at once and store all the configuration data in one component.

Complete the following steps to retrieve configuration data for a cell and all clusters in the cell from your source WebSphere Application Server environment and convert it into a template that can later be applied to your target WebSphere Application Server environment.

When you use this approach, keep the following items in mind:

• All configuration data for a cell and all the clusters in the cell is stored in a single component. The component does not include configuration data for nodes or servers.
• Because all configuration data for a cell and a number of clusters is stored in a single component, managing configuration data in a DevOps scenario might become challenging. For example, to make a change to ClusterABC, configuration data for the cell and all clusters is reapplied, which might take a long time if the cell contains many clusters.
• Cluster names are hardcoded in the configuration data. To alter cluster names when the configuration data is templatized, use the User Defined Tokenization field when you run the process.

1. From the IBM WebSphere Application Server – Configure plug-in page, download the WebSphere – Example 8 – Discover & Templatize Cell Configuration Data example process, and then import the process into UrbanCode Deploy.
2. Click the process name, and then click Design to open the process editor.
3. Click Edit (the pencil icon) on the WebSphere Configuration Discovery step.
4. Select Show Hidden Properties.
5. In the Limit Discovery Scope list, select Cell and Clusters.
6. Click OK, and then click Save.
7. On the Processes page, click Run for the process.
8. In the Run Process window, enter the following values in the fields:
   1. For Config File, enter the location and name of the initial configuration file to create. To save the configuration file in the working directory on the agent computer, leave the default value, which is discovered_configuration.txt.
   2. For Output Directory, enter the location and name of the directory to use to store the templatized configuration data. To store the template in the working directory, leave the default value, which is TemplatizedOutput.
   3. For User Defined Tokenization, specify values to update, or tokenize, in the configuration data. Put each entry on a separate line. Use the following format: oldValue->newValue. When the process runs, every instance of oldValue in your cell configuration data is replaced by newValue.
      Important: If variables such as INSTALL_ROOT or PROFILE_ROOT are different in the source and target WebSphere Application Server environments, you must update the configuration data with the correct values for the target environment. For example, if your source WebSphere Application Server environment was installed in /opt/IBM/WebSphere7/AppServer and your target WebSphere Application Server environment was installed in /opt/someDirectory/WebSphere/AppServer, the configuration data must be updated to replace /opt/IBM/WebSphere7/ with /opt/someDirectory/WebSphere/AppServer. Use the User Defined Tokenization field to update these values. For example, you can enter /opt/IBM/WebSphere7/->/opt/someDirectory/WebSphere/AppServer to replace the values in your configuration data.
   4. For Resource, click Set and then select the cell resource of the source environment to base your template on.
9. Click Submit to run the process.
10. After the process is complete, verify that a component was created in this format: Cell – cell name. Go to the Components page. Click the name of the new component, click the Versions tab, click the version, and then verify that the configuration data exists as a component version artifact.
    
11. Edit the component’s Apply process. View the properties of the Apply Config step. Check the Show Hidden Properties checkbox, then ensure the Only Update/Create Configuration Objects checkbox is checked. If it is not checked, configuration objects that exist in your target environment but do not exist in your source environment may be deleted.

Add components to the resource tree

In the Create the resource tree section of this document, you created resource trees for both your source WebSphere Application Server environment and your target WebSphere Application Server environment. Now you add components to the target WebSphere Application Server environment’s resource tree.

Add the cell component to the resource tree

1. In the resource tree, for the cell resource in the WebSphere Application Server environment, click Actions > Add Component.
2. In the Component list, select the component that contains your cell configuration data. The name is in this format: Cell – cell name.
3. Update the aliases property for the default host. Configuration data for a cell can contain a virtual host named default_host. The aliases property for the default_host host can contain hardcoded host names. These hardcoded host names must be updated in the configuration data before the data can be applied to a new environment. To simplify this process, the aliases property for the default_host host is replaced by a token (@DEFAULTHOSTVIRTUALHOSTALIASES@) in the configuration data. In the Role Properties section of the Create Resource window, enter the value for the aliases property of the default_host host. Use the following format: virtualHostName->virtualHostPort. Each entry must be separated by \n. Typically, you replace the host name with an asterisk (*). The default value for this field is *->9080\n*->80\n*->9443\n*->5060\n*->5061\n*->443.
4. Click Save.
5. Verify that the cell component is displayed directly under the cell resource that it manages.
   

Add node components to the resource tree

1. In the resource tree, for one of the node resources in the target WebSphere Application Server environment, click Actions > Add Component.
2. In the Component list, select the component that contains the configuration data for the node. The name is in this format: Node – node name.
3. Click Save.
4. Verify that the node component is displayed directly under the node resource that it manages.
5. Repeat steps 1 – 4 for each node that you plan to apply configuration data to. For nodes that will contain similar configurations, you can add the same component under multiple node resources in the resource tree.
   

Add server components to the resource tree

1. In the resource tree, for one of the server resources under the target WebSphere Application Server environment, click Actions > Add Component. If the server resource does not exist in the resource tree, complete these steps:
   1. Click Show > Resource Roles.
      
   2. In the Resource Roles filter pane, enter WebSphereServer to find the WebSphereServer resource role.
      
   3.  Drag the WebSphereServer resource role from the right pane to the Servers folder.
      
   4. In the window that opens, enter the name for the server, and then click Save.
2. In the Component list, select the component that contains the configuration data for the server. The name is in this format: Server – server name.
3. If the server is a member of a static cluster, enter the name of the cluster in the Cluster Name field. (Members of dynamic clusters do not have to be managed with configuration data because dynamic cluster members are managed by the dynamic cluster itself.)
4. Click Save.
5. Verify that the server component is displayed directly under the server resource that it manages.
6. Repeat steps 1 – 5 for each server that you plan to apply configuration data to. For servers that will contain similar configurations, you can add the same component under multiple server resources in the resource tree.
   Note: Your Deployment Manager and node agents can be managed by a server component, as shown in the following screen capture.
   

Add cluster components to the resource tree

1. In the resource tree, for one of the cluster resources in the target WebSphere Application Server environment, click Actions > Add Component. If the cluster resource does not exist in the resource tree, complete these steps:
   1. Click Show > Resource Roles.
      
   2. In the Resource Roles filter pane, enter WebSphereCluster to find the WebSphereCluster resource role.
      
   3. Drag the WebSphereCluster resource role from the right pane to the ServerClusters folder.
      
   4. In the window that opens, enter the name for the cluster, and then click Save.
2. In the Component list, select the component that contains the configuration data for the cluster. The name is in this format: Server – server name.
3. Click Save.
4. Verify that the cluster component is displayed directly under the cluster resource that it manages.
5. Repeat steps 1 – 4 for each cluster that you plan to apply configuration data to. For clusters that will contain similar configurations, you can add the same component under multiple cluster resources in the resource tree.
   

Adding combined components to the resource tree

If you combined the configuration data for a node and all the servers on the node into one component, add the component directly under the node resource. For more information, see the Add the Cell Component to the Resource Tree section of this document.

If you combined the configuration data for a cell and all the clusters in the cell into one component, add the component directly under the cell resource. For more information, see the Add Node Components to the Resource Tree section of this document.

Set up an application in IBM UrbanCode Deploy

In UrbanCode Deploy, applications consist of components that are deployed together. To set up a migration application in UrbanCode Deploy, complete these steps.

1.  From the IBM WebSphere Application Server – Configure plug-in page, download the WebSphere Configuration – Example Migration Application, and import the application into UrbanCode Deploy.
2. Click the application name. The Environments page is displayed.
3. Click Target WAS Environment.
4. Click Add Base Resources. The resource tree is displayed.
5. Select the top-level group for your target WebSphere Application Server environment, and then click OK.
6. Verify that your resource tree is displayed in the environment, as shown in the following screen capture:
   
7.  Open the Components page for the application, as shown in the following screen capture:
   
8.  Click Add Component.
9. In the Select a Component list, select all components that contain configuration information to apply to the target WebSphere Application Server environment. Click Save.
10. Verify that the components are displayed as part of the application, as shown in the following screen capture.
    

Apply configuration changes to the target WebSphere Application Server environment

At this point, you can apply configuration data to your target WebSphere Application Server environment.

1.  Go to Components page of the migration application.
   
2. Click Run Process for the cell component.
3. In the Environment list, select Target WAS Environment.
4. In the Resource list, select the component to apply.
5. In the Process list, select Apply (Template).
6. In the Version list, select the version of configuration data to apply.
   
7. Click Submit.
8. Wait for the process to finish.
9. Repeat steps 1 – 8 for each node component.
10. Repeat steps 1 – 8 for each server component.
11. Repeat steps 1 – 8 for each cluster component. For static clusters, see this section: Special considerations for static clusters.
12. Verify that your WebSphere Application Server target environment contains the migrated configuration.

Special considerations for static clusters

For static clusters, individual cluster members must be managed by a server component that contains server configuration data. All cluster members must exist in the target environment before you apply the cluster configuration. Cluster members are also listed in the configuration data for the cluster. To add or remove cluster members, you must edit the cluster configuration data. Cluster members are listed under the Cluster Members path in the JSON file. The following code is an example of how two cluster members are represented in cluster configuration data. The cluster member names and node name must match the values in your target environment.

{
        "description": "Discovered Cluster Members",
        "inheritTeam": "true",
        "name": "Cluster Members",
        "path": "/@websphere.cell@/ServerClusters/@websphere.cluster@/Cluster Members",
        "teamMappings": []
    },
    {
        "description": "Discovered WebSphereClusterMember",
        "inheritTeam": "true",
        "name": "JWC-CustomNode01Node01-amatthewMember1",
        "path": "/@websphere.cell@/ServerClusters/@websphere.cluster@/Cluster Members/JWC-CustomNode01Node01-amatthewMember1",
        "roleName": "WebSphereClusterMember",
        "roleProperties": {
            "websphere.clustermember.membername": "amatthewMember1",
            "websphere.clustermember.nodename": "JWC-CustomNode01Node01",
            "websphere.clustermember.weight": "2"
        },
        "teamMappings": []
    },
    {
        "description": "Discovered WebSphereClusterMember",
        "inheritTeam": "true",
        "name": "JWC-CustomNode01Node01-amatthewMember2",
        "path": "/@websphere.cell@/ServerClusters/@websphere.cluster@/Cluster Members/JWC-CustomNode01Node01-amatthewMember2",
        "roleName": "WebSphereClusterMember",
        "roleProperties": {
            "websphere.clustermember.membername": "amatthewMember2",
            "websphere.clustermember.nodename": "JWC-CustomNode01Node01",
            "websphere.clustermember.weight": "2"
        },
        "teamMappings": []
    }

Note: When you apply configuration changes that are related to static clusters, remember that cluster members must exist on the target environment before you apply cluster configuration data. In other words, apply the server (cluster member) configuration data first, then apply the cluster configuration data.

Optional: Build an application process to apply configurations

You can create a process that runs all the individual processes that apply configurations. To create such a process, complete these steps:

1. On the Process page of your migration application, click Create Process.
2. Enter a name, choose additional settings, and click Save.
3. Click Edit for the new process.
4. On the Design page, drag a Run Process for Each Version step from the step palette to the process designer.
5. Enter a Name for the step. For example, enter Apply Cell Config.
6. In the Component list, select your cell component.
7. In the Component Process list, select Apply (Template).
8. In the Max # of concurrent jobs field, enter 1. (Attempting to apply multiple WebSphere Application Server configuration changes simultaneously can cause errors.)
9. Click OK.
10. Repeat steps 4 – 9 for your node components.
11. Repeat steps 4 – 9 for your server components.
12. Repeat steps 4 – 9 for your cluster components.
    
13. Click Save to save the process.

To run the process:

1. Go to the Environments page for the migration application.
2. Click Request Process for the target environment, as shown in the following screen capture:
   
3. Clear Only Changed Versions.
4. In the Process list, select the process that you created.
5. Under Component Versions, click Choose Versions. The Component Versions window opens.
6. Select the version to apply for each component. To select versions for multiple components, click Select For All, as shown in the following screen capture.
   
7. Click OK.
8. Click Submit. The process runs.
   

Result

The WebSphere Application Server configuration is migrated from the source to the target WebSphere Application Server environment. After the migration, you can migrate applications.

Migration checklist

The following high-level checklist describes the actions to take for best results when migrating WebSphere Application Server configurations.

1. Read this document.
2. Manually copy and install files, such as resource adapter files and SSL certificates, from your source WebSphere Application Server environment to your target WebSphere Application Server environment.
3. Set up WebSphere Application Server topologies in the UrbanCode Deploy resource tree for both the source and target WebSphere Application Server environments.
4. Discover configuration data from the source WebSphere Application Server environment and convert the data into templates. Templates are stored as component version artifacts in UrbanCode Deploy.
5. Add components to the resource tree.
6. Set up an UrbanCode Deploy application.
7. Apply the configuration data to the target environment.

Troubleshooting

Out of memory error during discovery process

If a discovery process fails with an out-of-memory exception, increase the maximum heap size that the wsadmin command uses. The default setting is 512 MB. To update the maximum heap size, complete these steps:

1. Open the discovery process in the process editor, and edit the WebSphere Configuration Discovery step.
2. Select Show Hidden Properties.
3. Increase the wsadmin Max Heap value. By default, the wsadmin Max Heap field is set to -Xmx512m. For example, to set the maximum heap size to 2 GB, enter -Xmx2048m.
4. Save your changes to the process.

For more information on increasing the wsadmin command heap size, see the Troubleshooting page for the IBM WebSphere Application Server – Configure plug-in.

SOAP Connection timeout exception

If SOAP Connection timeout exceptions (java.net.SocketTimeoutException: Read timed out) occur, increase the SOAP Connector requestTimeout property. For example, to increase the requestTimeout property for the Deployment Manager, in the WebSphere Application Server admin console, click System administration > Deployment manager > Additional Properties > Administration Services > Additional properties > JMX Connectors > SOAPConnector > Additional Properties > Custom properties. Locate the requestTimeout custom property, and then modify the timeout value.