Completing component upgrades

Certain InterChange Server components require additional tasks to complete their upgrades. The following sections describe how to complete those upgrades:

Importing to an ICL

Important:
The need to perform the steps in this section depends on the version of your current InterChange Server:

Starting with version 4.2.0, development of ICS components is done locally instead of being done in the ICS instance (as in 4.1.1). Therefore, if you are upgrading from a 4.1.1 version, you must create an Integrated Component Library (ICL) within System Manager on the Windows machine running your Tools. The ICL holds your InterChange Server components. Refer to the System Integration Guide for instructions on how to create ICLs. After you have created the ICL (or ICLs), you are ready to import components from the InterChange Server repository on the UNIX machine.

Note:
It is recommended that you import the ICS components in pieces, importing a large chunk of data can be slow and might cause memory errors on System Manager. If you have an unusually large number of components, you might want to break down the import process even further. The recommended order of component import is as shown in Table 33.

Table 33. Order for import of ICS components

Order ICS component Steps to import
1 Business objects

Import the pre-existing business object definitions from the ICS repository to an ICL within System Manager. See the Implementation Guide for WebSphere InterChange Server for details on how to import components using the Import components wizard of System Manager.

2 Maps Completing collaboration template and map upgrades
3 Collaboration templates and collaboration objects Completing collaboration template and map upgrades
4 Connectors Completing connector upgrades
5 Relationships

Import the pre-existing relationship definitions from the ICS repository to an ICL within System Manager. See the Implementation Guide for WebSphere InterChange Server for details on how to import components using the Import components wizard of System Manager.

Completing collaboration template and map upgrades

This instructions in this section are only necessary if your are upgrading from version 4.1.1.

After you have upgraded the ICS repository, you are ready to complete the upgrade of any pre-existing maps and collaboration templates. This upgrade involves the following steps:

Upgrading component class files

It is important to check your pre-existing Java class (.class) files for maps and collaboration templates to ensure that the code is compatible with the new version.

Note:
Make sure that your class files reside in the appropriate directory of the new version, as follows:

Check for the following code in your pre-existing Java class files:

If you change any Java class file, you must recompile the code and redeploy the associated component to the ICS repository. For information on how to compile maps, see the Map Development Guide. For information on how to compile collaboration templates, see the Collaboration Development Guide. For more information on how to redeploy, see Deploying to ICS.

Converting components to the new format

Important:
The need to perform the steps in this section depends on the version of your current InterChange Server:

Collaboration templates and maps created with versions of the InterChange Server software prior to release 4.2.0 must be converted to a new format that is compatible with the current software. In the new format, all collaboration and map information is stored as part of the collaboration template and map definition in the repository.

Note:
Collaboration templates and maps created with versions of the InterChange Server software prior to release 4.0.0 use collaboration model (CollaborationName.clm) files and the map design (MapName.dlm) files, which are no longer required. Contact IBM technical support for assistance.

To convert collaboration templates and maps to the new format:

  1. Import the pre-existing maps and templates from the ICS repository to an integration component library (ICL) within System Manager running on a connected Windows machine. See the Implementation Guide for WebSphere InterChange Server for details on how to import components using the Import components wizard of System Manager.
    Note:
    The Import components wizard detects any maps or collaboration templates that are in a pre-4.2 format. In this case, it asks you if you want to convert them. To have maps and collaboration templates converted to the 4.3 format, make sure the Maps and Collaboration Templates check boxes are enabled.
  2. If you have not already compiled the imported maps and collaboration templates due to upgrades of the class files (see Upgrading component class files), compile them at this time. For how to compile maps, see the Map Development Guide. For how to compile collaboration templates, see the Collaboration Development Guide.
  3. Deploy the upgraded maps and collaboration templates to the ICS repository on the UNIX machine using the overwrite option. For more information, see Deploying to ICS.

Completing connector upgrades

This section provides information on the steps for upgrading a connector to the 4.3 version of InterChange Server:

  1. Install the relevant adapters.
  2. Upgrade the connector to the integration broker:
  3. If you have customized any connector startup scripts, you might need to upgrade them. For more information, see Upgrading connector startup scripts.
  4. Verify the connector upgrade. For more information, see Verifying connector configuration.

Upgrading connectors to new ICS

To obtain WebSphere Business Integration Adapters to work with your InterChange Server, you must install version 2.6 of a WebSphere Business Integration Adapter. However, for a new install, you cannot just copy any existing adapter directories (those in subdirectories of the ProductDir/connectors directory), because there are shared components that the WebSphere Business Integration Adapters Installer provides. There is no longer a single Installer for all adapters and therefore you must install each relevant adapter using its own Installer.

Note:
When InterChange Server is your integration broker, you do not need to install the Adapter Framework product separately. The Adapter Framework is included as part of the InterChange Server installation.

For more detailed instructions on how to install adapters, refer to the individual adapter guides.

If the ICS configuration file (InterchangeSystem.cfg) contains connector-agent information, a separate connector-specific configuration file will be created for each connector listed.

  1. The path to the configuration file has changed therefore you need to specify the fully qualified path to this file on the line within the custom connector startup script that calls the start_adapter.sh script. Do this by using the -c option, as follows:
    start_adapter.sh -dconnector_name -nconnector_name
     -cfully_qualified_name_of_new_config_file
    
  2. To incorporate an upgraded connector definition into your repository, use Connector Configurator (on the connected Windows machine running your Tools) to open the new connector definitions file provided with your connector (typically, the name of the provided file is connectorName.txt).

    With the file open in Connector Configurator, set the connector properties, and then choose Save As Project to save the configuration into System Manager. From System Manager you can deploy the new connector configuration to InterChange Server, as described in the Implementation Guide for WebSphere InterChange Server.

    Note:
    To ensure that you have the latest properties for the upgraded connector, refer to the appropriate adapter guide.

Migrating from a WebSphere message broker to ICS

To migrate your connectors from a WebSphere Message Broker (either MQ Integrator, MQ Integrator Broker, or Business Integration Message Broker) to the InterChange Server system release 4.3, follow these steps. Some of these steps must be completed on a connected Windows machine running your Tools.

  1. Use the System Manager tool to create a new Integration Component Library.
  2. Use the Connector Configurator to confirm that all queues specified in the local configuration are valid for InterChange Server.
  3. For each connector definition file, use the Connector Configurator to do the following:
    1. Change the DeliveryTransport connector property from WebSphere Message Broker-JMS to JMS.
    2. Change the RepositoryDirectory property to REMOTE.
    3. Upgrade connector properties, as follows:
      • Add or delete connector-specific properties. To ensure that you have the latest connector-specific properties for the upgraded connector, refer to the associated adapter guide.
      • Make sure all appropriate standard properties have a value. To ensure that you have the latest standard properties for the upgraded connector, refer to the appendix of standard properties in the associated adapter guide.
  4. Use the Save to Project option in the Connector Configurator to save the connector definition into the Integration Component Library.
  5. Use the Business Object Designer tool to upgrade the business-object-definition (.xsd) files to contain the locale information.
  6. Use the Save to Project option in the Business Object Designer to save the business object definition into the Integration Component Library.
  7. From System Manager, deploy the updated connector configuration and business object definitions to InterChange Server, as described in the Implementation Guide for WebSphere InterChange Server.

Upgrading connector startup scripts

All InterChange Server startup scripts have been changed to accommodate the migration from the VisiBroker ORB to the IBM Java ORB. If you have modified pre-4.2.2 connector startup scripts, similar changes also need to be made to the new startup scripts.

The 4.2.2 release introduced a new startup script structure with the following major changes:

Note:
Most existing IBM-delivered adapters do not yet use this new structure for their startup scripts. You do not need up modify the startup scripts of these IBM-delivered adapters. Only startup scripts for custom adapters should be modified.

If you have customized any connector startup scripts in a release prior to 4.2.2, you should re-examine them to ensure that your customizations appear in the correct file in this new startup-script structure which is also used by 4.3.

Note:
In the connector startup scripts, make sure you include the .jar files in the CLASSPATH (or JCLASSES) variable for any customized data handlers that your connector uses. In particular, verify the order that data handlers are listed in the CLASSPATH. For example, if you use the XML data handler, make sure that the CwXMLDataHandler.jar file is in front of the CwDataHandler.jar file. An xml.class file exists in both these .jar files and you want to ensure that the one in CwXMLDataHandler.jar is the one that is invoked.

Verifying connector configuration

After completing any connector upgrades or modifications, ensure that the connector is properly configured for the new environment. To do this:

Upgrading access clients

You must upgrade your access client to work with the IBM Java ORB or if you prefer with another ORB implementation which complies with CORBA 2.3. Contact your ORB vendor to make sure that your ORB is CORBA 2.3 compliant. The remainder of this section assumes that you are working with IBM Java ORB.

In order to upgrade an access client that currently uses VisiBroker ORB to use the IBM Java ORB instead, do the following:

If the access client is used from within a servlet, the IBM ORB is contained in the runtime of the WebSphere Application Server. Therefore, the following changes are required:

If a WebSphere Access for EJB is used, the IBM Java ORB is contained in the WebSphere Application Server runtime. In this case, the only change required is to remove the VisiBroker .jar references from the class path, because the Access for EJB .jar file contains all other necessary artifacts, such as the compiled IDL and Session Bean.

Upgrading other components

If you have created any other components that have custom .jar files (such as data handlers), you must copy the custom .jar files into the appropriate location in the new directory structure. Usually, custom .jar files reside in the lib subdirectory of the product directory.

Note:
You must also make sure that these custom .jar files are listed in the appropriate startup scripts. For more information, see Upgrading server startup scripts.

Upgrading the SNMP

Due to internal data structure changes in the SNMP Agent for the 4.3 release, the old state file (sts) will no longer be recognized. The state file contains information about the Agent's community names (which act like passwords), trap forwarding destinations, target ICS connections and the RBAC security username and password. After upgrading to the 4.3 release SNMP Agent, you will need to run the SNMP Configuration Manager to re-enter the information previously saved in the state file.

You must also manually reconfigure whatever Management Console is used with the SNMP Agent because the MIB file will change. The MIB file is used by the Management Console to know what kind of information is provided by the SNMP Agent. This file is modified in the 4.3 release, therefore users using the new SNMP Agent will need to load the new MIB file into their Management Console.

Note:
While the format of the configuration file is unchanged, the name of the file is changed from cwsnmpagent.cfg to wbi_snmpagent.cfg, it is therefore strongly recommended that you use the SNMP configuration wizard to create a new version. It is important to do this before launching the SNMP Agent.

Upgrading System Monitor

If you use System Monitor, existing Views and Monitors are migrated so that they are compatible with ICS version 4.3. This is done automatically when the user logs in to the System Monitor.

Handling user projects

Important:
The need to perform the steps in this section depends on the version of your current InterChange Server:

Importing existing projects

If you have exported your existing user projects, you can import them after ICS is running. Connect System Manager running on a connected Windows machine to your ICS instance and perform the following steps:

  1. Expand the User Projects folder, right click InterChange Server Projects, and select Import Solution.
  2. Select the folder location created during your export from your pre-4.3 version.
  3. Verify that all of your user projects were successfully imported.

Creating projects

It is recommended that you create a project for each interface and a separate project for common components (such as metaobjects and connectors). Connect System Manager running on a connected Windows machine to your ICS instance and perform the following steps:

  1. Right click on User Projects and select New User Projects.
  2. Assign a name to the user project. This name should uniquely identify the interface.
    Note:
    The name of a user project cannot be the same as an existing user project or an existing ICL project.
  3. Select the components for the user project. This step creates a shortcut to each of the required components. The components themselves remain in their ICL.

For more information on how to create projects, see the Implementation Guide for WebSphere InterChange Server.

Deploying to ICS

Important:
The need to perform the steps in this section depends on the version of your current InterChange Server:

With the ICL and user projects defined within System Manager on a connected Windows machine, you are ready to deploy the components to the InterChange Server repository on the UNIX machine. If you have not made any changes to your ICS components, the only components that need to be redeployed are maps and collaboration templates.

With System Manager connected to your ICS instance, perform the following tasks:

  1. Right click on the user project and select Deploy User Project.
  2. From the dropdown list of registered and connected ICS instances, choose the target ICS instance for deployment.
  3. Stop and restart InterChange Server.

See the Implementation Guide for WebSphere InterChange Server for details on how to deploy components to the server.

Copyright IBM Corp. 1997, 2004