Considerations for the IBM Integration Designer migration process

When you migrate from a previous version of Integration Designer or WebSphere® Integration Developer to IBM® Integration Designer V8.5.6, most of the migration is done automatically. However, there are a number of considerations to be aware of that might require additional manual configuration.

The following considerations are intended to help with the migration process:

Validations

With each new release, validators for various components, such as business objects, human tasks, and XSLT maps are improved. When you import the artifacts to a newer version, there might be validation errors that the previous validator did not catch.

Java validation

For using SDO API to create a data object, there is added Java validation in IBM Integration Designer:

It validates if a business object of the specified namespace and name exists. If it is invalid, you see the following error message in the Problems view:
```
A BO with namespace <namespace> and name <BO name> cannot be found.
```
It validates if the correct getter and setter methods are used based on the attribute type. If not, you see the following error message in the Problems view:
```
Incompatible method argument type.  
The <BO attribute name> field is of type <actual attribute type>.
```
It validates if the attribute referenced in the getter and setter methods exists. If not, you see the following error message in the Problems view:
```
The field <BO attribute name> does not exist in the Business Object <BO name with namespace>.
```

Java validation occurs in:

Java components
Custom mediation primitive in mediation flows
Java snippet activities in business processes
Custom mappings in business object maps

Quick Fix

In some cases, you can use the Quick Fix to fix the problem. Go to the Problems view, right-click the error or warning and check if Quick Fix is enabled. It usually helps to change the artifacts compliant to the validators more quickly.

SDO programming tips

From WebSphere Integration Developer 6.0.x to WebSphere Integration Developer 6.1, there are package name changes for a few classes, such as BOXMLSerializer, which might cause compilation errors. It is a good practice not to reference those classes directly, but to use Service Manager to locate the service.

From:

com.ibm.websphere.bo.BOXMLSerializer serializer = new 
com.ibm.websphere.bo.impl.BOXMLSerializerImpl();

To:

com.ibm.websphere.sca.ServiceManager srvMgr = 
com.ibm.websphere.sca.ServiceManager.INSTANCE;
com.ibm.websphere.bo.BOXMLSerializer serializer = (BOXMLSerializer) 
srvMgr.locateService("com/ibm/websphere/bo/BOXMLSerializer");

Circular dependencies

IBM Integration Designer might detect circular dependencies of the modules or projects as errors, while an older version of WebSphere Integration Developer does not. To quickly resolve this issue, you can change the compiler option from the Preferences. Go to Windows > Preference > Java Compiler > Building. Under the build path problems section, select the Warning option for Circular dependencies:

Use refactoring

If you must change the name of a component or its target namespace because they are invalid, use the refactoring capabilities instead of changing it in one place. If you do not use refactoring, you might encounter problems as the name or target namespace of a component might be referenced by other artifacts. Refactoring those values would preserve the relationships.

For example, a namespace must be an absolute Uniform Resource Identifier, for example, starting with http://. Refactor the target namespace by pressing Alt+Shift+R on the target namespace field of the Properties page.

XPath

XPath can be used in mediation flows (for example, MessageFilter primitive) and business processes (for example, Assign activity). Before version 6.1, WebSphere Integration Developer did not have a distinction between business object attributes defined as xsd:element and those defined as xsd:attribute. If XPATH is used, you might see the following message after migrating:

The <attribute_name> schema element was not found in the <xpath_expression> XPATH.

To fix this error, put an "@" symbol in front of the attribute name, or reselect the XPATH in the XPATH Expression Builder. For example, there is a business object that is named MyBO which has an attribute "myAttribute" defined as xsd:attribute. The XPATH expression that is created in 6.0x is:

/MyBO/myAttribute
Then change it to:
/MyBO/@myAttribute

Component-specific considerations

Business object map

For WebSphere Integration Developer 6.1.2 or later, if you have mappings that include an inherited type, you might receive the following warning message:

CWLAT0064W: The 4 transform includes an inherited type, 
which might produce unwanted side effects when the map runs.

Business object maps can work on generalizations of types, this warning is raised to indicate that the transform will still run even if the inherited type comes in as part of the instance document. This warning becomes more of a concern when mapping elements are involved in a substitution group. Typically, if the element is not involved in a substitution group, you do not need to be concerned about the warning.

MQ bindings: The MQ binding now uses an activation specification in its configuration rather than listener ports. If you are migrating an application that uses an MQ binding for an import or export from V6 to V7, you must update your binding configuration. For instructions about the required migration steps for the MQ binding, see the related task.