IBM BPM, V8.0.1, All platforms > Migrating and upgrading your IBM BPM environment > Migrating from other products > Migrating from WebSphere InterChange Server or WebSphere Business Integration Server Express

Postmigration considerations

When applications have been migrated from WebSphere InterChange Server or WebSphere Business Integration Server Express to IBM BPM, special attention is required in some areas to enable migrated applications to function in IBM BPM consistently with their intended function because of differences between the architectures of IBM BPM and WebSphere InterChange Server or WebSphere Business Integration Server Express.

You should be aware of the information described in the following sections if it applies to your application and environment:


Security

Additional security configuration is required for your applications to have the same security levels set as they had when running in WebSphere InterChange Server or WebSphere Business Integration Server Express. For details on this configuration, refer to Configure global security after WebSphere InterChange Server or WebSphere Business Integration Server Express migration.


Handling existing database connections, relationships, and scheduled events (InstallAdministrativeObjects.py script)

The Jython script InstallAdministrativeObjects.py is generated during migration. This script has three purposes:

You can run the script with the wsadmin command to create IBM BPM configuration definitions corresponding to the original WebSphere InterChange Server or WebSphere Business Integration Server Express artifacts. A copy of the InstallAdministrativeObjects.py script is included wherever the shared artifacts are included. That is, the script is included in every JAR file created by the reposMigrate command, and it is put in the shared library project specified during import in IBM Integration Designer. AnInstallAdministrativeObjects.py script is always generated even if there are no artifacts that require it. This script can be modified to add or delete entries before using the wsadmin command to run it.

For more information about using the wsadmin command, see wsadmin scripting tool .


Handling existing WebSphere InterChange Server or WebSphere Business Integration Server Express database connection pools

To preserve existing WebSphere InterChange Server or WebSphere Business Integration Server Express DataBase Connection pools for use by IBM BPM, you can run the InstallAdministrativeObjects.py script with the wsadmin command to create the connection pools in IBM BPM.

If an appropriate JDBC provider is not defined, this script will use default JDBC provider templates to create JDBC providers. A side effect of using these default templates is that IBM BPM creates an empty sample data source definition. This sample data source is not used; you must delete it to prevent exceptions from occurring during server start because it does not specify all of the information required for a data source.

In the WebSphere InterChange Server or WebSphere Business Integration Server Express environment, resources are defined only once for the entire system. To simulate this in the IBM BPM environment, the InstallAdministrativeObjects.py script defines resources at the cell scope. WebSphere variables are predefined at the node scope in the IBM BPM system for use by JDBC providers created from the default JDBC provider templates. These variables are defined at the node scope so that they can be customized for each node. Because of this scoping discrepancy, you will need to do one of the following:

Use the administrative console to examine the JDBC providers that are generated to determine which WebSphere variables are needed. From the administrative console, select Environment > WebSphere Variables to create any required variables. See Create, editing, and deleting WebSphere variables in the WebSphere Application Server ND information center.

Here is an example of what the generated InstallAdministrativeObjects.py script might contain to generate the JDBC connector pool:

dsName = "sqls"
create_datasource(dsName, JNDI_PREFIX + dsName, DATASOURCE_DESCRIPTION, MS_SQL_JDBC_PROVIDER_NAME, MS_SQL_JDBC_PROVIDER_TYPE, "icsadmin",  "icsadmin", 4, 50, "qaxs17", "1433", "wicsrepos")

For more information about the wsadmin command, see wsadmin scripting tool .


Use an existing WebSphere InterChange Server or WebSphere Business Integration Server Express relationship database

To use an existing WebSphere InterChange Server or WebSphere Business Integration Server Express relationship database in IBM BPM, you can use the InstallAdministrativeObjects.py script with the wsadmin command to create the data source and relationship configuration information in IBM BPM. Normally, IBM BPM automatically creates the configuration information for the migrated relationships when they are deployed. To be able to use the existing database, the InstallAdministrativeObjects.py script has to create the database connection for the existing WebSphere InterChange Server or WebSphere Business Integration Server Express relationship database and the relationship configuration information in IBM BPM. Run the InstallAdministrativeObjects.py script before you deploy the migrated components. Then, when IBM BPM deploys the relationships, it will use the configuration information that was generated by the script.

Here is an example of what the generated InstallAdministrativeObjects.py script might contain to generate the relationship database connection:

dsName = "ContactR"
create_datasource(dsName, JNDI_PREFIX + dsName, DATASOURCE_DESCRIPTION, MS_SQL_JDBC_PROVIDER_NAME, MS_SQL_JDBC_PROVIDER_TYPE, "icsadmin",  "icsadmin", -1, -1, "9.26.230.56", "1433", "wicsrepos")

create_relationship("ContactR", "jdbc/wbi60migration/ContactR", "false")
create_role("ContactR", "ID1", "", "null", "", "null")
create_attribute("ContactR", "ID1", "JtextEmployeeID")
create_role("ContactR", "ID2", "", "null", "", "null")
create_attribute("ContactR", "ID2", "EmployeeID")
create_role("ContactR", "ID3", "", "null", "", "null")
create_attribute("ContactR", "ID3", "EmployeeID")

For more information about the wsadmin command, see wsadmin scripting tool .


Migrating scheduled events

Because there is no IBM BPM component that corresponds to WebSphere InterChange Server or WebSphere Business Integration Server Express scheduler entries, migration of WebSphere InterChange Server or WebSphere Business Integration Server Express scheduler entries is accomplished by extracting the pertinent data from the existing WebSphere InterChange Server or WebSphere Business Integration Server Express repository JAR file and creating corresponding entries in the IBM BPM scheduler tables in the IBM BPM Common database. The data is represented in string form in the Jython script. To create the scheduler entries in the IBM BPM database, run the InstallAdministrativeObjects.py script with the wsadmin command.

Here is an example of what the generated InstallAdministrativeObjects.py script might contain to generate the scheduler entry:

create_scheduler_entry("true", "stop", "JDBCConnector", "Connector", "2006-09-07T10:44:29.000PDT", "undefined", 0, 0)
   create_scheduler_entry("true", "start", "JTextConnector", "Connector", "2006-09-07T10:47:06.000PDT", "undefined", 0, 0)
   create_scheduler_entry("true", "stop", "jtext_jdbcCollab", "Collaboration", "2006-09-07T10:48:10.000PDT", "undefined", 0, 0)
   create_scheduler_entry("true", "start", "jtext_jdbcCollab", "Collaboration", "2006-09-07T10:48:10.000PDT", "undefined", 0, 0)
   create_scheduler_entry(true, "START", "JDBCConnector", "Connector", "2006-10-22T12:34.56.789CDT", "MINUTES", 20, 0):


Access Enterprise JavaBeans (EJB) support

WebSphere InterChange Server or WebSphere Business Integration Server Express supports the triggering of collaborations by client code using the Java™ EE EJB (Enterprise JavaBeans) protocol. Support for this method of triggering collaborations is referred to as "AccessEJB" or "AccessEJB for EJB" support. For compatibility with earlier versions, IBM BPM provides support for AccessEJB. The AccessEJB support assumes that the SCA BPEL modules to be invoked were generated by the WebSphere InterChange Server or WebSphere Business Integration Server Express migration tools described in this documentation. The mapping from the collaboration name and port name (that is, the input parameters for the AccessEJB) to the SCA module name, interfaces, and business object types assume the conventions used by the migration tools. The AccessEJB support in IBM BPM is delivered in the AccessEJB.zip project interchange file. This file is located in the INSTALL_ROOT/HeritageAPI directory. The AccessEJB support consists of an EJB (AccessEJB) that references an SCA module project (DynamicRouting) that invokes the SCA BPEL module. This SCA BPEL module is the migrated version of the collaboration that was invoked in WebSphere InterChange Server or WebSphere Business Integration Server Express. The DynamicRouting module uses a selector component to select the correct SCA target based on the collaboration name and port name passed to the AccessEJB. To enable AccessEJB support in IBM BPM, do the following:
  1. Import the WebSphere InterChange Server or WebSphere Business Integration Server Express repository containing the collaboration that is the target of the AccessEJB invocation into IBM Integration Designer.

    From the Import page, select ProjectInterchange and click Next.

  2. From the Import Projects page, import the AccessEJB.zip project interchange file into .

    Select the check box for each of the projects you are importing.

    For example, for an AccessEJB import, select AccessEJB, AccessEJBApp, AccessEJBEJB, AccessEJBEJBClient and AccessEJBWeb. Similarly, if you are using Dynamic Routing, select all of the projects that apply to DynamicRouting and click Finish.

    The AccessEJB.jar is packaged at version 6.1, so if you import this jar file to a later version (for example, version 6.2 or later) you need to perform a workspace migration. If this is the scenario, detects this and notifies you that you need to migrate the workspace. The Workspace Migration welcome page displays.

    Performing a Workspace Migration

    1. From the Workspace Migration Welcome page, click Next to display the page that list the workspace projects to be migrated.

    2. From the list of projects, click Select All to select all of the projects and click Next to display the Migration Project Resources page.

    3. From the Migration Project Resources page, review the files to be migrated, and then click Next to display the Undefined Server Runtime page.

    4. From the Undefined Server Runtime page, make sure that IBM BPM version 8.0.1 Server is selected as the New Server Runtime and that all of the AccessEJB / Dynamic Routing Projects are still selected. Click Next to display the Complete Migration Startup page.

    5. From the Complete Migration Startup page, click Finish to initiate the migration of the projects you have selected.
  3. Open the DynamicRouting project and update the selector table to include the migrated module that is to be invoked via the AccessEJB.

  4. Go to the migrated project containing the BPEL component to be invoked via the AccessEJB EJB, and drag the export that references the BPEL module over to the DynamicRouting project.
  5. Repeat steps 3 and 4 for each BPEL module that is to be accessible via AccessEJB.
  6. Build the project and deploy it to the IBM BPM server.
  7. Ensure that any required data handlers are provided in the runtime class path of the IBM BPM server.

  8. To enable your Access client to use IBM BPM, ensure that it points to the IBM BPM server and uses the JNDI name com/crossworlds/access/business/cwsession/CwSession when looking up the Access EJB.


DynamicSend API configuration

In WebSphere InterChange Server or WebSphere Business Integration Server Express, the DynamicSend API can be used to directly invoke one collaboration from another. The collaboration to be invoked does not have to be predetermined; instead, it can be determined dynamically at run time. The support for the DynamicSend API in IBM BPM uses the DynamicRouting project described in Accessing Enterprise JavaBeans (EJB) support. Follow the instructions in Enabling the BaseCollaboration.dynamicSend method call to enable the DynamicSend API to be able to invoke the specified BPEL modules.


Enabling the BaseCollaboration.dynamicSend method call

To enable the WebSphere InterChange Server or WebSphere Business Integration Server Express BaseCollaboration.dynamicSend method call to work correctly after migration, you must modify the DynamicRouting Projects in the AccessEJB Project Interchange file. This requires two main procedures:
  1. Migrating the WebSphere InterChange Server or WebSphere Business Integration Server Express repository.
  2. Enabling the DynamicSend API.
To migrate the WebSphere InterChange Server or WebSphere Business Integration Server Express repository:
  1. Import the WebSphere InterChange Server or WebSphere Business Integration Server Express repository containing the collaboration that invokes DynamicSend API into .
  2. Import the WebSphere InterChange Server or WebSphere Business Integration Server Express repository containing the collaboration or connector that is the target of the DynamicSend API invocation into .
  3. Build all, and correct all errors.
To enable the DynamicSend API:
  1. Import the AccessEJB.zip project interchange file into IBM Integration Designer.
  2. Open the DynamicRouting project, and add the WebSphere InterChange Server or WebSphere Business Integration Server Express shared library into the DynamicRouting project's dependencies.

  3. Go to the migrated module containing the component to be invoked through the BaseCollaboration.dynamicSend method, and drag the export that references the module over to the DynamicRouting project. Choose Import with SCA Binding and then click OK.

  4. In the DynamicRouting Assembly Diagram window, copy and paste PreRoute_TargetCollab_TargetPort and then rename the newly created copy to PreRoute_ ModuleName_ExportName (the name of the copied import will be PreRoute_TargetCollab_TargetPortCopy).

  5. On PreRoute_ ModuleName_ExportName, left-click the reference, which is the small box attached to the right containing 1.1. Right-click and choose Delete.
  6. Wire the PreRoute_ ModuleName_ExportName to the import generated in step 3. Respond with no to the Java WSDL reference question.
  7. Rename the import to ModuleName_ExportName. Save the changes to the Assembly Diagram.
  8. Update the selector table in the DynamicRouting project to include the migrated module that is to be invoked through the DynamicSend API.
    1. Switch to the Java Perspective Package Explorer View. Expand DynamicRouting/com.ibm and open RoutingSelector.selt with the text editor.

    2. Copy the OperationSelectionRecord block and paste the entire block immediately following the existing block.

    3. In the new block, change componentName="PreRoute_TargetCollab_TargetPort" to componentName="PreRoute_ ModuleName_ExportName". Also in the new block, change value="TargetCollab_TargetPort" to value=" ModuleName_ExportName".
      <OperationSelectionRecord>
            <SelectionKey>
            <SelectionKeyElement xsi:type="selt:StringSingletonKey" value=
                 "TargetCollab_TargetPort"/>
            </SelectionKey>
            <SelectionData xsi:type="selt:SCAInternalComponent"
                  componentName="PreRoute_TargetCollab_TargetPort"/>
            </OperationSelectionRecord>
            <OperationSelectionRecord>
            <SelectionKey>
            <SelectionKeyElement xsi:type="selt:StringSingletonKey"
                   value=" ModuleName_ExportName"/>
            </SelectionKey>
            <SelectionData xsi:type="selt:SCAInternalComponent" componentName
                   ="PreRoute_ ModuleName_ExportName"/>
      </OperationSelectionRecord>
    4. Save and close RoutingSelector.selt.
  9. Generate the implementation file.
    1. Expand com.ibm.sel and copy PreRoute_TargetCollab_TargetPortImpl.java and paste it to the same location. Name the newly created Java file PreRoute_ ModuleName_ExportNameImpl.java.
    2. Edit PreRoute_ ModuleName_ExportNameImpl.java. Change the method name of locateService.TestBOInterfacePartner to locateService_ InterfaceNamePartner ( InterfaceName is the method). Change TestBOInterfacePartner to InterfaceNamePartner.
    3. Search for " locateService_TestBOInterfacePartner" in PreRoute_ ModuleName_ExportNameImpl.java, and change its name to locateService_ InterfaceNamePartner.
    4. Search for " this.locateService_InterfaceNamePartner().invoke("Sync", tmpres)" in PreRoute_ModuleName_ExportNameImpl.java, and change its name to " this.locateService_InterfaceNamePartner.invoke("Sync_ExportName", tmpres)", Save it.
  10. Switch back to the Business Integration Perspective. Open the DynamicRouting Assembly Diagram. Click PreRoute_ ModuleName_ExportName. Open Properties and select Implementation. In the Class: field, enter com.ibm.sel.PreRoute_ ModuleName_ExportNameImpl.
  11. Save all changes.
  12. Repeat steps 3 to 11 for any other modules that you want to call from the BaseCollaboration.dynamicSend Method. There is currently no way to "dynamically look these modules up" if you do not add them to the DynamicRouting Table so you can access them during run time.

  13. For the project that calls the dynamicSend API, do the following

    1. Copy and paste Interface "RoutingPacket" from Module DynamicRouting.

    2. In the component that calls the dynamicSend method, add the newly copied interface "RoutingPacket" to Reference_Partners, and rename it "RoutingPacketPartner."
    3. Save it.
    4. Open the Assembly Diagram. Drag "RoutingInput" from DynamicRouting. Choose "Import with SCA Binding" and click OK. Rename it from "Import1" to "DynamicRouting".
    5. Delete and re-drag the component that calls the dynamicSend API to the Assembly Diagram window. Wire the Reference "RoutingPacketPartner" to "DynamicRouting" and re-wire the other references.
  14. Save all and build, then correct all errors. Export all the modules to EAR files.


Event sequencing migration

Methods are available for sequencing events with IBM BPM in ways similar to the way you could with WebSphere InterChange Server or WebSphere Business Integration Server Express. Articles on this subject that you might find helpful are available from the IBM developerWorks website. Search in the "Technical Library" at http://www.ibm.com/developerworks.


Failed events

Methods for handling failed events in IBM BPM are described in articles that you might find helpful on the IBM developerWorks website. Search in the "Technical Library" at http://www.ibm.com/developerworks.


Map migration

WebSphere InterChange Server or WebSphere Business Integration Server Express migration converts WebSphere InterChange Server or WebSphere Business Integration Server Express maps into IBM BPM maps. Two output maps are generated: the business graph map and the business object map. The business graph map calls the business object map as a submap. All the business graph maps are identical in structure. Differences include names, names of the submap they call, or ASI information on the verb attribute. These business graph maps are present only to satisfy the necessary mapping steps that can only be done at the business graph level. The business object maps are each unique and are the migrated forms of the WebSphere InterChange Server or WebSphere Business Integration Server Express maps. If the WebSphere InterChange Server or WebSphere Business Integration Server Express input map contains custom messages for the supported WebSphere InterChange Server or WebSphere Business Integration Server Express API log methods, these messages will be converted into a properties file.


Collaboration migration

Collaboration Templates: The WebSphere InterChange Server or WebSphere Business Integration Server Express to IBM BPM migration tools migrate WebSphere InterChange Server or WebSphere Business Integration Server Express collaboration templates into IBM BPM BPEL files. One BPEL file is created for each triggering port defined in a collaboration template, and its name is based on the following naming convention: CollaborationTemplateName_TriggeringPortName. Each BPEL file receives a business object type that is based on the business object type associated with the triggering port.

For example, if the triggering port takes a business object type of Customer, the BPEL file that is created will have a “TriggeringBusObj” variable type of Customer.


Collaboration Objects: The WebSphere InterChange Server or WebSphere Business Integration Server Express to IBM BPM migration tools migrate collaboration objects into several service component architecture (SCA) components. Currently, migration supports collaboration objects that reference collaboration templates as follows:


SCA Components:

For detailed information on how collaboration templates are migrated to IBM BPM BPEL files, see the IBM developerWorks article Migrating WebSphere InterChange Server or WebSphere Business Integration Server Express artifacts to IBM BPM artifacts, Part 1: Migrating collaboration templates to BPEL .


BPEL variables must be defined after migration

Problem: A variable that is not defined in the Ports definitions of the WebSphere InterChange Server or WebSphere Business Integration Server Express collaboration template is used to invoke a partner. After migration, the variable is referenced in the business process execution language (BPEL) invoke but has not been set up as a BPEL variable, so it is flagged as an error when executing the serviceDeploy command against the module or after building the module in . Cause: When calling a partner from a BPEL process in IBM BPM, any object used in the call must be declared as a BPEL variable so that the type of the object being used can be determined. During migration, only the Ports declarations in the collaboration template are examined to determine which BPEL variables need to be declared. For global variables, or variables declared in snippets elsewhere in the ICS Collaboration Template definition, the migration code cannot reliably determine the object type, so BPEL variables are not declared for these in the BPEL file generated by migration. Solution: After migration, you must define the variable as a BPEL variable for the variable to be referenced during a call.


Enabling logError API email notification on WebSphere Process Server

Problem: After migration to IBM BPM, the WebSphere InterChange Server or WebSphere Business Integration Server Express logError API does not send an email to a list of users that has been configured in WebSphere InterChange Server or WebSphere Business Integration Server Express. Cause: In WebSphere InterChange Server or WebSphere Business Integration Server Express, you could configure the API call logError to send an error email to a specified list of users. However, this list of users, configured on the server, is not accessible to the migration code so it must be set up manually in IBM BPM. Solution: To enable the WebSphere InterChange Server or WebSphere Business Integration Server Express logError email notification functionality in IBM BPM, a new BPEL environment variable called LOGERROR_EMAIL_LIST is created in each BPEL file generated by migration. Set this variable with the list of email users needing to receive log error emails. Separate the names within the list with a comma.


Handling asynchronous calls in IBM BPM

Problem: Async-in events act as triggering events when both types of events can be received on the same connector. Cause: If both async-in and triggering events can be received on the same connector, the migrated application cannot determine which events are which type. By default, all events are treated as triggering events in a migrated application in this scenario. Solution: Application-specific logic that can determine if an event is async-in or triggering must be added to the migrated application. Migrated modules that can receive triggering events and async-in events on the same connector will have a component named JavaSelector. The implementation code for the JavaSelector component will contain the AsyncIn() method shown below. This method must be updated with logic to check if events are async-in or triggering. This logic will be specific to each application and will be based on the nature of the events being handled.
 /** * Method generated to support async inbound service call routing */
 public boolean isAsyncIn()
 { //Add custom code here 
    //TODO 
    return false;
 }


Handling correlation values in IBM BPM

Problem: In IBM BPM, new events attempting to use the existing correlation values will fail. In such instances, the error message
CWWBE0074E: Correlation violation in activity 'null' for correlation set 
'CorrelationSetA'java.sql.
SQLException: Could not insert new row - duplicate value in a UNIQUE INDEX column
appears. Cause: When a collaboration or process instance completes in WebSphere InterChange Server or WebSphere Business Integration Server Express, data related to that instance is deleted except for cases dealing with failures. In IBM BPM, the persistence of process instance-related data is controlled by the business process execution language (BPEL) option, "Automatically delete the process after completion." BPEL files generated by the WebSphere InterChange Server or WebSphere Business Integration Server Express to IBM BPM migration wizard will not have this option selected. As a result, process instance data will persist, even after the process instance completes, until you clean it up manually. When a process defines a correlation set, the correlation values locked by process instances remain locked for as long as the process instance data is persisted, even after the process has completed. As a result, new events attempting to use the same correlation values will fail as long as the previous process instance's data persists. This behavior will be different from the behavior in WebSphere InterChange Server or WebSphere Business Integration Server Express, where new events with duplicate correlation set values could be processed as soon as the previous instance was complete. Solution: To simulate the behavior of WebSphere InterChange Server or WebSphere Business Integration Server Express with respect to multiple events with duplicate correlation set values, you can choose to select the BPEL option "Automatically delete the process after completion" so that process instance data is deleted, and the correlation value is unlocked, as soon as the process instance completes. Before selecting this option, you should investigate and fully understand the way failures are handled in IBM BPM, to ensure that your failed event strategy does not rely on data that will be automatically deleted when this option is set.


Packaging and deploying migrated applications

After migrating the WebSphere InterChange Server or WebSphere Business Integration Server Express repository using the reposMigrate command, you will need to package the resulting JAR files into EAR files in order for them to be deployed to IBM BPM. To do this, you can either import each migration-generated JAR file into IBM Integration Designer and export the modules as EAR files, or you can use the serviceDeploy command.

The serviceDeploy command accepts a JAR file as input and outputs a deployable EAR file. Packaging the migration code into EAR files involves compiling the resulting migrated JAR file. If this produces validation errors, they are most likely caused by the use of unsupported WebSphere InterChange Server or WebSphere Business Integration Server Express APIs or third-party APIs that were present in WebSphere InterChange Server or WebSphere Business Integration Server Express but have not yet been included in the IBM BPM class path. Remove the unsupported APIs and add the third-party classes to the IBM BPM class path.

Validation errors may also be caused by not following premigration recommended practices or may indicate postmigration work that still needs to be performed on the artifacts. As with migration errors, each validation error should be handled on a per-error basis. If a recommended premigration practice was not followed, you can update the repository and migrate it again, or you can edit the output artifacts to remove the problem.

Any other validation errors should be resolved as if these artifacts were created from scratch. Refer to the validator documentation that outlines common artifact errors and their resolutions. Inevitably an automated migration cannot account completely for your program's intent; it can just make best guesses. Therefore, even if there are no validation errors, it is possible that the migrated artifacts do not perform as intended. Review all artifacts to confirm that the intended purpose of each artifact is met by its migrated content.

: Migrating from WebSphere InterChange Server or WebSphere Business Integration Server Express


Related tasks:

Configure global security after WebSphere InterChange Server or WebSphere Business Integration Server Express migration


Related reference:

serviceDeploy command
Premigration considerations
Limitations when migrating from WebSphere InterChange Server or WebSphere Business Integration Server Express


Related information:

wsadmin scripting tool
IBM developerWorks
Migrating WebSphere InterChange Server artifacts to WebSphere BPM artifacts, Part 1: Migrating collaboration templates to BPEL
Create, editing, and deleting WebSphere variables