Migrating WebSphere Business Integration Server Foundation V5.1.x projects to WebSphere Process Server V6

This article shows how to migrate a simple business process from WebSphere® Studio Application Developer Integration Edition v5.1.x to the WebSphere Integration Developer v6.0 tooling environment. It also covers how to deploy and test that process in WebSphere Process Server v6.0. After reading this article, you will discover how the programming model has changed and how to create and wire the service types that were available in WebSphere Studio Application Developer by using WebSphere Integration Developer.

Ashok Iyengar (ashoki@us.ibm.com), Senior Software Engineer, IBM WebSphere Enablement Team

Ashok Iyengar photoAshok Iyengar is a senior software engineer with the WebSphere Enablement Team based in San Diego, California. He works on pre-sales engagements focusing on business integration and portal. His current passion is process portals. He is a co-author of IBM WebSphere Portal Primer.



Cheryl Sedota, Software Engineer, IBM

Cheryl SedotaCheryl Sedota is a software engineer working with the WebSphere Process Server and WebSphere Integration Developer development teams in Austin, Texas. She works on migration from WebSphere Business Integration Server Foundation v5.1 to WebSphere Process Server v6.0.



28 September 2005

Introduction

IBM® WebSphere® Process Server v6 (hereafter called Process Server), the next generation of Business Integration software from IBM, is based on a service-oriented architecture (SOA) that embraces open standards. It supercedes WebSphere Business Integration Server Foundation v5.1.x (hereafter known as Server Foundation). The Integrated Development Environment (IDE) has also evolved from WebSphere Studio Application Developer Integration Edition (hereafter called Application Developer) v5.1.x to the new WebSphere Integration Developer v6 (hereafter called Integration Developer). Integration Developer, the tooling that complements Process Server, is based on Eclipse 3.0 and brings a whole new paradigm of component-based development

Previously calledNow called
WebSphere Business Integration Server Foundation v5.1.xWebSphere Process Server v6
WebSphere Studio Application Developer Integration Edition v5.1.xWebSphere Integration Developer v6

When migrating business integration applications from Server Foundation to Process Server, you can follow one of two paths:

  • One is runtime migration, which moves the entire Server Foundation configuration (including installed applications and configuration files) to a Process Server profile. The application binaries are unchanged and they "just run" as they did in Server Foundation. This migration path is not available in WebSphere Process Server v6.0.0, but it is being considered for a future version of the product.
  • The other option is source artifact migration, which uses the migration tooling in the new IDE. This is the only option available in v6.0.0. In this case, the source code for the application is migrated to the new programming model and reworked so that you can deploy a migrated application to Process Server.The Migration Wizard automatically migrates all BPEL files and BPEL WSDL extensions for you, then you must perform a set of manual migration steps to complete the migration.

This article describes the source artifact migration path. You should have some experience using Application Developer and a fair understanding of Java™ programming and business processes.


Overview of source artifact migration

This article captures the steps to migrate the source artifacts of a simple service project that contains a business process exposed as an EJB, wired to a Java service. In this example, the business process simply invokes the Java service, which in turn sends an email. This action helps you know when the application has been executed successfully by receiving an email. The application was created in Application Developer and deployed in Server Foundation. We show you how to import the project into Integration Developer using the Migration Wizard, re-wire the components, and get it ready for deployment on Process Server.


Existing resources

The existing Application Developer project interchange zip file contains six projects that make up the enterprise application. The working part of the application is contained in the EmailService service project. The EmailServiceCustomWeb project contains a JSP that allows you to invoke the service from a Web browser. These projects were both deployed in the EAR defined by EmailServiceEAR.

We will use Integration Developer to migrate the service project and custom Web project, and use the migrated JSP to test the business process. Except for extracting the project interchange zip file, all the steps were performed in Integration Developer v6.0.0 on a Windows® platform.

Unzip the project interchange file into a temporary folder. Then start the Integration Developer from the Windows Start Menu. Select Start -> Programs -> IBM WebSphere -> Integration Developer V6.0 ->WebSphere Integration Developer V6.0.


Using the Migration Wizard

There are two ways to access the Migration Wizard. When you first bring up WebSphere Integration Developer, the Welcome screen displays a few icons. Click the green arrow icon to bring up the Migration Wizard as shown in Figure 1.

Figure 1. WebSphere Integration Developer Welcome screen
WebSphere Integration Developer Welcome screen

Tip: While working with the Migration Wizard, turn off the project auto-building in Integration Developer. Go to Main Menu -> Project, and un-check Build Automatically. If you turn off the AutoBuild option, remember to periodically build the entire project or re-enable the AutoBuild option.

The next screen presents you with three source migration options. Click the icon that has 5.1 with an arrow as shown in Figure 2.

Figure 2. WebSphere Integration Developer initial migration screen
WebSphere Integration Developer initial migration screen

Another way is to go through the Integration Developer via the File Import option. To start, use the Main Menu:

  1. Go to File -> Import.
  2. Select WebSphere Studio Application Developer Integration Edition Service Project from the Import Window, as shown in Figure 3, then click Next. This starts the Migration Wizard.
    Figure 3. Import window
    Import window
  3. Click the Browse button and go to the temporary folder where you unzipped the project interchange zip file.
  4. Highlight the project folder that you want to import and click OK. In this example, you import the EmailService project as shown in Figure 4.

    Tip: The wizard is smart enough to fill in the Module name it finds. In case it does not, enter the project module name. We recommend that you use the same old project name.

    Figure 4. Specifying the source artifacts
    Specifying the source artifacts
  5. Click Next to proceed to the screen where the migration options are set.
  6. Make sure to check the option to Preserve the original BPEL Java snippets in the comments. This preserves all existing Java snippets by enclosing them in comment blocks. Click Finish.
  7. The Migration Wizard creates a new "Business Integration Module" project, imports all the existing Application Developer artifacts, and converts the source artifacts. You see a Migration Results screen with some messages.

    In this case, you see 5 informational messages. Four of those say: "The following java package is not being migrated because it contains generated classes that are no longer valid". These are harmless messages. The packages had been automatically generated by Application Developer to bind the application to the Server Foundation runtime. The new tools will generate new bindings. Click OK.

    Note: If there were errors, you can highlight one of those message lines and click the Generate ToDo’s button to produce TODOs in the code so you can fix them at a later time.

    If you had turned off the AutoBuild option, you can turn it back on again (Integration Developer Main Menu -> Project -> Build Automatically).


Working with migrated resources

Now you will work with the migrated resources.

  1. Go to the Business Integration perspective in Integration Developer. In the navigation pane, open the newly created EmailService project by double-clicking on the Assembly Diagram icon, Assembly Diagram icon, named EmailService. It opens in the Assembly Editor.
  2. You see a single item in the canvas named EmailBusinessProcess. This is the Service Component Architecture (SCA) component whose implementation is the Email Business Process implemented in the Business Process Execution Language (BPEL).
    Figure 5. Assembly Editor showing the single Business Process component
    Assembly Editor showing the single Business Process component
  3. On the left side of the Assembly Editor is the tools palette. You need the Stand-alone References tool from the second tool set, where it is represented by a boxed blue arrow icon. Click it and place it on the canvas by clicking to the left of the Business Process Component. Drag the Business Process Component to the right if you need room.
  4. Click the green Wire icon, green Wire icon, in the Assembly Editor tool palette, then click the Stand-alone References component, and finally click on the Business Process Component (EmailBusinessProcess).
  5. A message pop-up tells you that "a matching reference will be created on the source node. Do you want to continue?". Do not check the "Always create without prompt" box. Click OK.
  6. A Select Interface window pops up as shown in Figure 4. You see two interfaces, where you can create references, ProcessPortType and MailSMTP. Select MailSMTP and click OK.
    Figure 6. Interface selection screen
    Interface selection screen
  7. You are asked whether you would like a Java interface to be generated for the Stand-alone Reference rather than a Web Services Description Language (WSDL) interface. You will use a JSP, a Java client, to access the process. Therefore, choose Yes.
  8. Click Ctrl-S to save the Assembly Diagram that looks similar to Figure 7. Observe the details of each of the components and the wire in the Details tab of the Properties pane.
  9. Select the Stand-alone References Component. In the Properties view, make note of the name of the Partner Reference in the Details pane. In this case, the name is MailSMTPPartner. In the Details pane, you can find the name of the Java Interface that was automatically generated for the client to use. As you can see in Figure 7, the interface is com.scb.process.email.mail.smtp.MailSMTP.
    Figure 7. Assembly Diagram showing the properties pane and two wired components
    Assembly Diagram showing the properties pane and two wired components

    Note: Why did we provide a Stand-alone Reference to the Business Process Component? Stand-alone References allow non-SCA clients (such as J2SE or J2EE clients like a JSP) to access SCA Components. If you plan to use only the BPC Explorer or the Component Test Framework to invoke the process, you do not need the Stand-alone Reference because these built-in tools use the BPC and SCA APIs to directly invoke the process.

  10. Back in the Assembly Editor, select the EmailBusinessProcess component’s reference connector (represented by a little box on the right with 1:1). Right-click on it and from the context menu, choose Wire References to New -> Components.

    This action creates a Generic SCA Component with the same name as the interface, MailSMTP, to the right of the EmailBusinessProcess component. This automatically wires the Business Process Component to the new Generic Component.

  11. Click Ctrl-S to save the Assembly Diagram.
  12. Right-mouse click on the Generic Component MailSMTP and from the context menu, choose Select Implementation -> Java. The Generic Component turns into a Java Component. In the Select entries field of the Pick Implementation screen, begin typing mailsm until you see a class named MailSMTP. Highlight it and click OK.

    Tip: The Qualifier field displays the name of the package as it existed in the old Application Developer service project. This is why you must have prior knowledge of the service project's structure before you start the migration process.

    This sample Java service has simple types as its input/output parameters (string and boolean), hence the SCA framework automatically equates the WSDL interface exposed by the SCA component and the Java class’ interface. For example, compare MailSMTP.wsdl and MailSMTP.java in the EmailService project. Switch to the Java perspective to view these files in Integration Developer.

    If you are not sure whether your Java interface is compliant with the SCA WSDL to Java requirements, instead of choosing Select Implementation, choose Generate Implementation. You are asked for a package into which the class can be generated. The wizard generates a SCA-compliant Java interface from the WSDL interface exposed by the component. The class for the component, MyComponent, is named MyComponentImpl.java.

    Now examine the type of each method’s input parameters as well as its return type to ensure that they all match your Java class' interface. If they do not match, you have two options. The first option involves modifying the interface of the original Java class. Or, you can use this generated skeleton as the implementation class and write custom code to invoke the original Java class for each method in the generated Java skeleton. This is usually a problem when an operation’s input or output type is complex (for example, a Customer object that has sub-objects like address, name, and so on) because in the SCA paradigm, they are represented as commonj.sdo.DataObject. In the original Java class, the parameters are represented as Java beans.

  13. The generic SCA component changes to a Java Component and the Business Process Component is wired to it. The canvas looks similar to Figure 8. The only visible change on the canvas is the "J", denoting that MailSMTP is a Java Component.
    Figure 8. Assembly Diagram showing the three wired components
    Assembly Diagram showing the three wired components
  14. That's it. Click Ctrl-S to save the Assembly Diagram and close the Assembly Editor.

The next step is to migrate the Web project contained in the Application Developer Project Interchange file.


Migrating the JSP used to invoke the business process

In the Application Developer Project Interchange file, the EmailServiceCustomWeb project contains a JSP (index.jsp) that takes the four parameters from the user and invokes the business process using the facade Enterprise Java Bean (EJB). This facade EJB was generated in Application Developer and is contained in the EmailServiceEJB project.

In Integration Developer, there is no facility to generate a facade EJB because it makes use of the new abstraction layer in the SCA programming model. Therefore, you have to migrate index.jsp to use the SCA programming model, which invokes the business process.

  1. First, import the EmailServiceCustomWeb project from the project interchange zip file. In Integration Developer, go to File -> Import -> Project Interchange. Click Next and browse to the zip file. Select EmailServiceCustomWeb as shown in Figure 9 and click Finish.
    Figure 9. Project import screen
    Project import screen

    Many of the environment variables that were valid in Application Developer are no longer used in Integration Developer, so we need to fix the classpath of the Web project.

  2. Switch to the Java perspective, Window -> Open Perspective - > Other -> Java, and select the EmailServiceCustomWeb project. Right-mouse click and select Properties.
  3. Go to Java Build Path and on the Projects tab, remove the dependency on EmailServiceEJBClient. Ensure that there is a dependency on EmailService as shown in Figure 10.
    Figure 10. Projects in the Java Build Path
    Projects in the Java Build Path
  4. On the Libraries tab, highlight all entries and click Remove to remove all JARs and class folder from the build path.
  5. Click Add Library, highlight JRE System Library, and click Next. In the Alternate JRE field, use the drop-down selector to choose WPS Server v6.0 JRE. Do not choose WebSphere v6 JRE. Click Finish.
  6. Click Add Library, highlight WPS Server Target, and click Next. Check "Configure wps server classpath" and click Next. Your properties screen looks like Figure 11.
    Figure 11. Libraries in the Java Build Path
    Libraries in the Java Build Path
  7. Click on Project References. Set a reference to the EmailService project as shown in Figure 12, and remove all other references.
    Figure 12. Project References settings
    Project References settings
  8. Click OK to save the new settings. This clears all the errors, except for the JSP compile errors in index.jsp. Application Developer v5.1 was at the J2EE 1.3 level. You are ready to migrate the Web application to the J2EE 1.4 level that is available in Integration Developer v6.0.

    Tip: The migrate option is available only after you enable the Advanced J2EE feature in your workspace. To do this, go to Window -> Preferences -> Workbench -> Capabilities -> Advanced J2EE -> Enterprise Java as shown in Figure 13.

    Figure 13. Turning on capabilities of the workbench
    Turning on capabilities of the workbench
  9. In the navigation pane, highlight the EmailServiceCustomWeb project. Right-mouse click and from the context menu and select Migrate -> J2EE Migration Wizard.
  10. On the J2EE Migration Wizard Welcome screen, ignore the warnings and click Next. The default settings are acceptable for this scenario. Figure 14 shows that the default J2EE version is v1.4 and the target server is WebSphere Process Server v6.0. Click Finish.
    Figure 14. Migration settings for the project
    Migration settings for the project
  11. Look for the message "Migration finished successfully". Click OK. Because this is a simple project, the Details pane indicates many of the items did not need migration.
  12. There is one final step. You need to add this custom Web project to the enterprise application that was generated for the EmailService Business Integration Module. This is done in the Integration Developer’s J2EE perspective and involves a few steps.
  13. Switch to the J2EE perspective, Window -> Open Perspective -> J2EE. In the navigation pane, go to Enterprise Applications -> EmailServiceApp -> Deployment Descriptor. Open the Deployment descriptor for EmailServiceApp.
  14. In the main window, click on the Module tab. Under Modules, click Add as shown in Figure 15. The Add Module window that pops up finds the EmailServiceCustomWeb project. Select it and click Finish.
    Figure 15. Project Reference settings
    Project Reference settings
  15. Click Ctrl-S to save the deployment descriptor for the application.
  16. In Integration Developer, the facade EJB is no longer generated for a business process. You must manually migrate this code to use the SCA programming model to invoke the business process. This is why you need to fix the errors in the index.jsp file.

    While in the J2EE perspective, edit index.jsp. In the Project Explorer pane, go to Dynamic Web Projects -> EmailServiceCustomWeb -> Web Content ->index.jsp. Double-click on index.jsp to open it for editing. Select the Source tab of the JSP Editor. You see errors inside of the "if" block as shown in Figure 16.

    Figure 16. Editing the index.jsp file
    Editing the index.jsp file
  17. Replace that block of code with the following:

    com.scb.process.email.mail.smtp.MailSMTP service = 
          (com.scb.process.email.mail.smtp.MailSMTP)   
          com.ibm.websphere.sca.ServiceManager.INSTANCE.
          locateService("MailSMTPPartner");
    
    boolean success = service.sendEmail(
          request.getParameter("server"), 
          request.getParameter("from"),
          request.getParameter("to"), 
          request.getParameter("contents"));
  18. Save the changes to index.jsp and the Deployment Descriptor.

Now you can test by performing the three methods listed below, where each test sequentially tests the components of the application.


Testing a migrated component using the Integration Developer integration test client

You can now test the migrated application in Integration Developer. The integration test client allows you to test each component individually, using the embedded test server to run the application.

  1. Go to the navigation pane of the Business Integration View. Right-mouse click on the EmailService project. From the context menu select Test -> Test Module. For the component to test, select MailSMTP.

    Note: You can choose the component that gets invoked. In this first case of MailSMTP, which is the Java Component that will be selected. Later, you will perform a more comprehensive test that invokes the business process component, once it is determined that the Java component works properly.

    Figure 17. Invoking events
    Invoking events
  2. On the Events screen, enter values for the four Input request parameters (the name of your email server, your email addresses, and the text to use as the content of the email) and click Continue.
  3. The Deployment Location window pops up. Choose the highlighted WebSphere Process Server v6.0 and click Finish.
  4. The integration test client starts the embedded Process Server test server, installs and starts the migrated application, and invokes the MailSMTP Java service with the parameters you specified. If the input parameters are correct, you see the value of the returned result as "true" as shown in Figure 18.
    Figure 18. Returned results
    Returned results
  5. Verify that the Java service was successfully invoked by checking if an email was sent to the recipient as shown in Figure 19.
    Figure 19. Test email
    Test email

    This test showed how you can invoke the Java Component (MailSMTP) using the Integration Developer integration test client.


Testing more migrated components using the Integration Developer integration test client

  1. Go back to the Events screen by right-clicking on the EmailService project in the Business Integration perspective and from the context menu, select Test -> Test Module.
  2. In the Component field, click the drop-down arrow and choose the component named EmailBusinessProcess. This is the business process component whose implementation is the BPEL process. It invokes the MailSMTP Java service that you just tested. This is a more comprehensive test. It demonstrates how to incrementally test the components in a Business Integration module.
  3. Enter values for the four request parameters as was done in the previous test and click Continue.
    Figure 20. Selecting the component
    Selecting the component
  4. This also results in a successful test where the recipient gets the test email and the Events screen shows the result as shown in Figure 21.
    Figure 21. Successful results
    Successful results

Testing the migrated application using the migrated JSP

You can now test the migrated application using the migrated JSP. This is a comprehensive test because it represents an end-to-end scenario.

  1. Go to the navigation pane in the J2EE perspective. Expand Enterprise Applications and right-mouse click on the EmailServiceApp project. From the context menu, select Run -> Run on Server.
  2. In the Server Selection screen, choose WebSphere Process Server v6.0 as shown in Figure 22, and click Finish.
    Figure 22. Defining a new test server
    Defining a new test server
  3. The Process Server test server starts and the application is published to it. In the main window of the Integration Developer, a Web browser window opens. By default, it points to http://localhost:9080/EmailServiceCustomWeb/ as shown in Figure 23.
    Figure 23. Web browser inside of WebSphere Integration Developer
    Web browser inside of WebSphere Integration Developer
  4. In the Web browser screen, enter values for the four Input request parameters, then click Enter. Remember to enter the name of your email server and your own email addresses. (The authors do not wish to get all those test emails!)
  5. If all goes well, you see the message of "Result is: true" printed in the lower part of the Web page. Verify that the JSP actually did call the business process successfully. The JSP invoked the stand-alone reference that you created, which in turn invoked the migrated business process and the Java service. The testing will be complete when the recipient receives an email as shown in Figure 24.
    Figure 24. Test email
    Test email

    Note: If you had turned off the AutoBuild option, you can turn it back on again (Integration Developer Main Menu -> Project -> Build Automatically).

You have successfully tested the migrated application in three different ways, preparing you for a full end-to-end scenario in your environment.


Conclusion

This article showed how to migrate a simple business process that sends an email, how to run it in a WebSphere Process Server runtime, and how to test that migrated process. Migrating a simple service project from WebSphere Studio Application Developer Integration Edition v5.1.x to work in WebSphere Integration Developer v6.0 is straightforward, particularly if it has a single project file like the EmailService sample and some simple Java code. We understand this is an atypical example of a BPEL business process, but it was used to introduce the Migration Wizard in Integration Developer and to get a feel for source artifact migration. We expect that real world migration projects will make use of the Migration Wizard, but it will also involve a fair amount of manual migration tasks.


Download

DescriptionNameSize
Code sampleProjectInterchange.zip  ( HTTP | FTP | Download Director Help )228 KB

Resources

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into WebSphere on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=WebSphere
ArticleID=94688
ArticleTitle=Migrating WebSphere Business Integration Server Foundation V5.1.x projects to WebSphere Process Server V6
publish-date=09282005