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.x, 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. The ICL holds your InterChange Server components. Refer to the System Integration Guide for instructions on how to create ICLs. Once you have created the ICL (or ICLs), you are ready to import components from the InterChange Server repository.

Note:
It is recommended that you import the ICS components in pieces, importing a large chunk of data can be slow and could 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 17.

Table 17. 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

Once 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.

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, seeUpgrading connector startup scripts.
  4. Verify the connector upgrade. For more information, see Verifying connector configuration.

Upgrading connectors to new ICS

To enable WebSphere Business Integration Adapters to work with your InterChange Server, you must install version 2.4 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), as they are shared components that the WebSphere Business Integration Adapters Installer provides. Because there is no longer a single Installer for all adapters, you must install each relevant adapter using its own Installer.

Note:
When InterChange Server is your integration broker, you need to install the Adapter Framework product.

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. Specify the local configuration file that has been updated for the specific connector:
    1. Navigate to Start > Programs > IBM WebSphere Integration Adapters > Adapters > Connectors > Connector Name.
    2. Right click on the connector name and select Properties.
    3. Insert the -c filename command at the end of the Target field's path, where filename is the fully qualified path of the local configuration file that has entries for that connector.
  2. To incorporate an upgraded connector definition into your repository, use Connector Configurator 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.

If you are upgrading your WebSphere Business Integration Adapters product and using ICS as the integration broker, you must reapply any customizations to your adapter shortcuts. The shortcuts are overwritten during the adapter upgrade.

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, follow these steps:

  1. Copy the connector-specific configuration and business-object-definition (.xsd) files from your WebSphere Message Broker directory to your InterChange Server directory.
  2. Confirm that all queues specified in the local configuration are valid for InterChange Server.
  3. Use the Connector Configurator tool to change the DeliveryTransport connector property from WebSphere Message Broker-JMS to JMS.
  4. Use the Connector Configurator tool to change the RepositoryDirectory property to REMOTE.
  5. Upgrade connector properties:
  6. Use the Business Object Designer tool to upgrade the business-object-definition (.xsd) files to contain the locale information.
  7. Use the System Manager tool to create a project that contains the connector-specific configuration and business-object-definition files.
  8. Deploy the project to the ICS repository. Refer to the Implementation Guide for WebSphere InterChange Server for information to deploy the project.

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.3 connector startup scripts, similar changes should be made to the new startup scripts also.

This release introduces a 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. Yo u 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 previous release, you should re-examine them to ensure that your customizations appear in the correct file in this new startup-script structure.

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 files exists in both these.jar files and you want to ensure that the one in CwXMLDataHandler.jar is the one that is executed.

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

Since VisiBroker has been replaced with IBM ORB since 4.2.2, VisiBroker may not be present with version 4.3.0 of InterChange Server. The IBM ORB that comes with the 4.3.0 installation is the only supported access client. A few changes must be made to the old access clients to work with version 4.3. The code change is as follows:

...
Properties orbProperties=new java.util.Properties();
orbProperties.setProperty("org.omg.CORBA.ORBClass", "com.inprise.vbroker.orb.ORB");
orbProperties.setProperty("org.omg.CORBA.ORBSingletonClass", 
"com.inprise.vbroker.orb.ORBSingleton");
org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init((String[])null, orbProperties);
...

Remove the two lines that contains setProperty() method calls which reference VisiBroker classes(com.inprise.vborker.org.*) to let the framework use the default ORB implementation of JDK instead of VisiBroker.

Access clients work with any standard ORB that is CORBA 2.3 compliant. For non-IBM ORBs, refer to that particular ORB vendor for any possible compatibility issues.

Access client can still use IgetInterchangeAccessSession() method to get its access session as shown:

accessSession = accessEngine.IgetInterchangeAccessSession(userName, passWord);

With new security mechanisms introduced in version 4.3, it is recommended that you use the SecureLoginUtility to obtain access session instead as shown:

Properties props = new Properties();
props.put("username", "admin");
props.put("password", "admin");
accessSession = SecureLoginUtility.login(accessEngine , props);

This way, the username and password are encrypted. It prevents any confidential information from being eavesdropped during transmission.

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.

Handling user projects

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

Importing existing user projects

If you have exported your existing user projects, you can import them once ICS is running. Connect System Manager 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 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.

Copyright IBM Corp. 1997, 2004