Introduction

In WebSphere InterChange Server (hereafter called InterChange Server) users can create collaboration templates. These collaboration templates were an intricate part of their various InterChange Server projects. They defined the logic that a business object must pass through bending and shaping that business object before spitting it back out to be picked up and interpreted by the next InterChange Server component it was intended for. Now IBM® has introduced WebSphere Process Server (hereafter called Process Server) to help customers and developers of InterChange Server to move to this new server. This article helps developers, who are familiar with their InterChange Server collaboration templates, to distinguish between their well-known and often loved artifacts and the migrated equivalent, a Process Server BPEL, as well as understand why they are seeing what they are seeing. This article explores the advanced collaboration template to BPEL concepts, it does not cover the basics.

At this point, you know how to run the migration tools and you understand the purpose of the artifacts generated in Process Server v6.0 covered by the following two articles:

• Migrating WebSphere InterChange Server solutions to WebSphere Process Server V6: Part 1, A simple migration example
• Migrate WebSphere InterChange Server solutions to WebSphere Process Server V6: Part 2, Artifacts generated by migration

In this article, you further explore the migration of collaboration template (CWT) artifacts, particularly around the enhancements added in v6.0.2.

Back to top

Decision nodes

In your InterChange Server collaboration templates, it was possible to create a decision node. They allowed you to tell the collaboration to follow a specific path based on some conditions. There were three types of decision node types: normal, default, and exception. The normal decision node type allowed the developer to provide a condition in which part of the decision node would execute if the condition was true. The default type was required. It said that if none of the other choices were true, then the execution follows that path. Finally, the exception type allowed execution to follow a path when an exception has occurred. This article is not intended to teach InterChange Server. For information about decision nodes, see the InterChanger Server documentation.

Suppose you had a simple decision node in InterChange Server that had the following types as shown in Figure 1.

For this simple example, we assume that both options lead to a success node.

As seen from the migrated BPEL, there are no decision node in Process Server. Instead, there are links that go directly from the node that was before the decision node (in this case, an empty node) to the conditioned nodes that follow the decision node. As you can see, there are two success nodes with links that look like they have small diamonds in them. These diamond shaped symbols indicate that the link has a condition associated with it.

This link is followed only if the condition defined in the InterChanger Server normal type decision node link is met.

This link is followed only if the condition defined in the InterChange Server normal type decision node link is not met. In our example, there will never be a case where this link is followed because of the logic that is used to determine whether or not the link is followed (always evaluated to false).

The last type is the exception link. When an exception link is defined in InterChange Server, there are a predefined set of possible exception types as shown in Figure 6.

During migration, the node in the BPEL immediately before the InterChange Server decision node is encapsulated within a sequence. On the sequence, a catch block is created that catches any exception that occurs in the code.

If an exception is thrown, the WICSFault block is executed. The Java™ snippet immediately following executes code similar to that shown in Figure 8.

First it checks the type of the exception. If it matches the type, then it sets a variable saying the exception was thrown equal to true. Then, just like the condition and default link types set a condition on the links, the exception link checks to see if the exception variable is set to true. The normal and default links in this case also need to check to make sure that an exception did not occur because they will only be followed if an exception does not take place.

After migration, a business object (BO) is created with a naming convention like the following: <scenario name>Exception_var.xsd. This BO holds all the exception variables that were created for the collaboration template.

You should now understand how Process Server migrates a decision node from InterChange Server, including which BPEL nodes are created, how the link conditions are set, and what Process Server exception handling capabilities are like.

Back to top

WebSphere Process Server fault handling

As mentioned in the Decision nodes section, fault handling is handled by surrounding a block of nodes that can throw an exception within a sequence. On that sequence, the BPEL checks the type of the WICSFault to determine which variables to set. hat was not mentioned in the decision node exception link section was the use of the BO, WICSFault. The WICSFault BO is always created during migration.

The type, subtype, and description are populated when a new exception or fault has occurred. It is sent through the system through the various components so that the information about the original problem is maintained between components.

You should now understand how fault handling is setup within the migrated artifacts. You can change the WICSFault BO that is created. This includes information important to you while determining how to handle your faults that are thrown.

Back to top

For loops

There is actually no while loop node in InterChange Server. The InterChange Server equivalent is the iterator node that we briefly mentioned in the Break node section below. When defining the properties of the iterator node in InterChange Server, you can define a for loop by specifying a start value, condition, and increment as shown below.

We will use one example for this section and the section on break nodes. See Figure 14 Figure 15 for screen shots of the InterChange Server collaboration template that relate to this example.

During migration, the loop conditions are used to set the condition on the resulting while loop. The while loop uses Java code to create the condition, and this condition is setup as a Java if statement. You'll notice that an initializing Java snippet is required to set a variable that is used to check whether the condition has been met. This variable has the naming convention of whileNode_<whileNodeId#>. It is initialized to be the value of the Start value defined by the collaboration template loop definition (in Figure 12, the whileNode variable is initialized to 0).

The while loop Java code is as follows:

boolean toReturn = false;
if (whileNode_3<23){ 
  whileNode_3 = (whileNode_3) + 2;
  toReturn = true;
}

Within the BPEL while loop node, the variable is checked against the condition that is defined in the collaboration template (in this example, the condition is <23). Finally, the increment variable is added to the current value of the iterator variable. The increment value for this example is 2.

In the two other types of iterator node iterations, Iterate attributes on a business object and Iterate Business Objects in an array, the resulting BPEL is similar to the scenario just described. An initialize variable is declared and initialized. It stores the current value. Then, the condition is tested against this current value. This is either the current value less than the number of attributes on a business object, or the size of the array. Finally, for these two types of iterations, the current value is incremented by 1.

You should now understand why Process Server must use a while loop to handle InterChange Server for loops. At this time, this is the easiest and most straightforward solution. If you decide a for loop is not necessary, you can simply delete the Java snippet code that initializes the for loop variables, and take all of the code inside the while loop and put it within the BPEL.

Back to top

Break nodes

InterChange Server can create break nodes. These break nodes tell the collaboration template that whenever they are encountered, the current while loop is stopped immediately, and the next piece is executed. Figure 14 shows a very simple example of what a break node looks like in InterChange Server.

As you recall, break nodes are only allowed to be placed within InterChange Server iterator nodes. Therefore, in the above example, an iterator node is placed in the main scenario of the collaboration template. Inside the iterator, the collaboration has the following nodes as shown in Figure15.

Recall that the break nodes were distinguished by the following symbol: .

When the above collaboration template is migrated using the InterChange Server to Process Server migration wizard in WebSphere Integration Developer (hereafter called Integration Developer), the resulting BPEL looks similar to Figure 13 in the for loop section.

Process Server does not have a break node equivalent. Therefore, during migration, the break node goes through some fancy steps for the InterChange Server collaboration template to behave the same as it did in InterChange Server. You'll notice that in place of the break node, a Java snippet exists. What had to be done to imitate the functionality of a break node was to set a boolean variable to be true when the break node was reached. The while loop (which is the same as an InterChange Server iterator node) iterates on the same condition it did in InterChange Server with the added condition that the break node has not yet been reached. If you are familiar with Java, you can see how the break node now functions as a means to break out of the while loop once the break node is reached as shown in Figure 16.

Before the while loop is executed, you need to set the break variable to false because it has not been reached yet. To initialize the variables, there is a Java snippet right before the while loop, Initialize Variables_6.

As you can see from the while loop Java, it first checks to see if the break node is set to true. If it is set to true that means that the break node has occurred, and therefore the while loop should no longer be executed. Otherwise, it continues on with the condition, executing the information within the while loop.

What might grab your attention from the snippet is that we are not using the break_10 variable directly, but instead getting it from somewhere else. That somewhere else is a global BPEL BO that is created during migration to hold all of the break variables for each scenario.

In this case, there is only one break variable for the old collaboration template. Therefore, there is only one break boolean variable declared within the new BO. There is a break variable BO for each scenario, which makes it really easy to locate the variables you are using. In this case, the scenario that this break node is defined in is called "myScenario". Therefore, the BO you find the boolean for this break variable is located in myScenarioBreak_var.xsd.

You should now understand the workaround for creating break nodes in Process Server.

Back to top

Receive choice

To allow the resulting Process Server BPEL to handle both asynchronous and synchronous execution, a receive choice is used rather than a receive. Use the receive choice for every single BPEL that is created as a result of an InterChange Server to Process Server migration.

The BPEL sets a variable equal to true if the sync path was taken, false if the asynchronous path was taken.

The BPEL only returns if it was initialized asynchronously.

The link condition Java code checks to see what the BPEL's sync variable is, and sets it equal to a useLink variable. The value of the useLink variable is returned. If false, the link is not followed, and therefore, the BPEL does not reply. Otherwise, if the useLink variable link is true, the BPEL does reply.

You should now understand why a receive choice is used instead of a basic receive at the beginning of a BPEL process.

Back to top

Asynchonrous inbound

Receive choice activities are also used when an asynchronous inbound operation is called.

The receive choice activity is used rather than a receive activity because the InterChange Server asynchronous inbound call has a timeout value set. If it had not, then a receive choice is not necessary.

The timeout value is set in InterChange Server by double clicking on the service call (for example, node labeled port1.Create node 7 in Figure 24), and selecting the Advanced button as shown in Fgure 26.

Now the asynchronous inbound call in Process Server either continues executing when it receives the inbound information it is looking for, or when the timeout value is reached.

Back to top

Multiple triggering ports

One of the most confusing aspects to migration is that before you only had one collaboration template, and after migration you end up with several. This section explains the reason.

The first rule to remember is that you have x number of BPELs created for each triggering port defined in your collaboration template. The naming schema of the BPELs is based on those triggering ports. For example, suppose you had two triggering, ports A and B, for a collaboration template named Collab. After migration, you have two BPELs, Collab_A.bpel and Collab_B.bpel.

All of the scenario code is repeated between the two BPELs. This means that if you want to change what a scenario does, you have to do it in more than one place. Sometimes one BPEL will not ever call a certain scenario, but because the two BPELs are exact replicas of each other, other than the triggering aspect of the BPELs, the scenario will still be present. If you know which scenarios are important for each BPEL that is created, you can delete the unused scenarios completely.

Each scenario is triggered by a verb. In InterChange Server, there are four default types that you can use to trigger a scenario:

• Create
• Update
• Delete
• Retrieve

The only requirement on a BO is that there is at least one verb associated with it.

There is only one BO type that is associated with each triggering port, so each of the BPELs created will only take in BOs that have a type equivalent to the triggering port type. Therefore, if one triggering port takes a BO of type Customer, then the BPEL created will have a TriggeringBusObj of type Customer. If another BPEL created is triggered by a BO of type x, then the created BPEL will have a TriggerBusObj variable of type x.

The migrated BPELs that are created use a case block to determine which scenario is triggered. Figure 29 shows a BPEL that triggers to the same scenario on all four verbs.

You can use any of the verbs to trigger the scenario code that follows the case in a flow. If, for example, the scenario is duplicated between two BPELs, but is not triggered by the triggering port that is represented by the current BPEL, then the code will be empty. For example, the useLink is always false and the scenario is never executed.

How the BPELs are wired together inside the projects to get multiple BPELs to function the same way as the collaboration template functions in InterChange Server will be discussed in a follow on article on collaboration objects.

You should now understand how multiple triggering ports are handled during Process Server migration, and why multiple BPELs are created. Also, the differences between the various BPELs that are created should be clear.

Back to top

Loop unraveling

When migrating to Process Server, you have the option to either maintain loops that might have existed in the collaboration template, or unravel those loops. This section describes a simple example that shows the before and after for the loops.

If during migration the option to maintain loops was checked, then the resulting BPEL looks like Figure 31.

Notice the red x's on all of the links that make the BPEL form a loop.

The errors occur because the tooling does not support loops at the time this article was written. However, the runtime does support loops. You can manually go in and change the namespace for the BPEL and the BPEL then runs as is with loops. The drawback to this manual fix is that the BPEL is no longer able to be viewed in the BPEL editor in Integration Developer unless the namespaces were changed back. You can do a simple search and replace when looking between the two views, but this is cumbersome.

Now suppose that the same collaboration template was migrated, and this time the maintain loops option was not selected.

This workaround is similar to the break node and for loop workaround. This time, the initializing Java snippet code, Initialize Variables_5, defines a variable that is true only during the first iteration as shown in Figure 33.

The firstTime variable is changed immediately to false the first time that the while loop is executed. This ensures that the loop happens at least once.

After the first execution, the loop is only going to happen if the condition is met (in this example, the condition is when 2 < 25). If the condition requires another loop variable to be tested or initialized, it will happen in the same initialize variables Java snippet node. All of the nodes that were involved in the loop itself are now inside the while loop. As you can imagine, the size of this while loop and its complexity grows exponentially with the complexity of the InterChange Server loops.

You should now understand why there are two options for handling your InterChange Server repositories that might include a collaboration template with a loop, how each option is handled during migration, and what you can expect to see in your BPELs as a result.

Back to top

Correlation sets

Correlation sets are setup for you when you migrate over to Process Server from InterChange Server. However, there is no guarantee that the resulting correlation sets are going to behave exactly as they had in InterChange Server. Because of this, you receive a warning during migration that is similar to the following:

CWWIC3002E: Correlation Sets have been setup for simpleCorr_customerPort, however, they
may not work exactly as expected.

In InterChange Server, there was only one correlation set that was used. Process Server allows you to specify multiple correlation sets. Therefore, during migration the correlation set information is all stored in just one new correlation set in Process Server.

In the above example, there is a correlation set defined on a synchronous call. The correlation set has an Id, Message, and ObjectEventId. When we migrate this collaboration template, we get the following BPEL as shown in Figure 36.

Notice that there is a correlation set defined under our list of correlation sets. It is given the name of CorrelationSetA. There is always only one correlation set defined after migration. However, in Process Server, you are free to add as many as you want.

The migrated BPEL initializes the correlation set on both the asynchronous receive choice option and the synchronous receive choice option. You can see the initialization by clicking on the Properties tab in Integration Developer, and then going to the Correlation section. The CorrelationSetA has an Initiation value of Yes.

Every time the BPEL uses the correlation set, it has to be defined. In our example, there was a synchronous call in InterChange Server that used the correlation set. Therefore, in the migrated BPEL, if the invoke is selected (Process Server node for a synchronous call), under the correlation section, notice the CorrelationSetA is used, but is not initialized. You can initialize the correlation sets once so the value is set to No.

If there are any properties associated with the correlation set, they are defined in the properties panel once the correlation set is selected.

In our example, only the Id was selected in the InterChange Server correlation set declaration, and therefore, only this property was migrated over to the new correlation set that was created.

You should now understand that correlation sets are setup as best as possible during migration, but they still require some manual manipulation. This is as simple as testing to make sure they are functioning as desired, or reworking the correlation sets within the BPEL components that invoked them.

Back to top

Custom collaboration properties

You can think of collaboration objects as defining an instance of a collaboration template. Therefore, with each instance, the ability to change the value of a collaboration property was allowed in InterChange Server. To provide the same functionality in Process Server during migration, a collaboration template is not generated as output until after the collaboration objects have been migrated. Therefore, if a custom property is changed by the collaboration object, the corresponding collaboration template also has those changes.

You can find the custom properties within a collaboration template in InterChange Server under the Template Definitions under the Properties tab as shown in Figure 40.

As you can see in this example, there is a custom property named prop1 of type String. In the collaboration template, its default value is set to value1TEMP.

The collaboration object associated with this collaboration template sets the value of this property to value1COLLAB.

In this case, the collaboration object wants the property, prop1, to be value1COLLAB.

After migration, the custom properties that were defined for the collaboration template are now defined for the BPEL. You can find them under the Environment tab in Integration Developer once the BPEL is open and selected. As you can see, during migration the value of the custom property for the collaboration template is value1COLLAB, and not the template's original value of value1TEMP.

More information about collaboration objects and the resulting SCA components that are created during migration will be explained in a follow on article. However, you should now have a good understanding about where custom properties are set and how they relate to a collaboration object.

Back to top

Conclusion

While the new BPEL artifacts that are migrated out of an InterChange Server collaboration template might be alien at first glance, there are similarities between the two. You learned that you can migrate over as many collaboration templates as you want and explore the results that are produced. You also learned how BPEL components are created and how to manipulate each of them if you change your BPEL functions. This article is one of many articles describing the migration between an InterChange Server repository and the resulting Process Server artifacts. Follow on articles will explore Process Server SCA components generated after migrating your InterChange Server collaboration objects.

Resources

Learn

• Read about a simple migration scenario: Migrating WebSphere InterChange Server solutions to WebSphere Process Server v6
  
  
• Find product documentation, installation, and migration instructions for the server as well as the tooling: WebSphere Process Server and WebSphere Integration Developer V6 Information Center.
  
  
• Get the technical resources you need for WebSphere Business Integration products: WebSphere Business Integration zone.
  
  
• Find technical resources for all of IBM's business integration offerings: IBM WebSphere Integration site.
  
  
• Learn about WebSphere Business Integration family of products and resources available: New to WebSphere Business Integration page.
  
  

Get products and technologies

• Build your next development project with IBM trial software, available for download directly from developerWorks.
  
  

About the author

Lisa Seacat is a Software Engineer at the IBM Austin Lab in Austin, Texas. She is a part of a team of developers working on migration support in WebSphere Process Server for WebSphere InterChange Server. Specifically, she has been the principal technical developer on the migration of InterChange Server collaboration templates into WebSphere Process Server BPELs and InterChange Server collaboration objects into Process Server SCA components. She received her B.S. degree in Computer Science from Carnegie Mellon University.

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Decision nodes
• WebSphere Process Server fault handling
• For loops
• Break nodes
• Receive choice
• Asynchonrous inbound
• Multiple triggering ports
• Loop unraveling
• Correlation sets
• Custom collaboration properties
• Conclusion
• Resources
• About the author
• Comments

Next steps from IBM

• Try: WebSphere Integration Developer (in the SOA Sandbox: Connect)
• Demo: Process automation, adoption pattern
• Briefing: WebSphere flexible business processes
• Buy: WebSphere Integration Developer (in the SOA Sandbox: Connect)

Dig deeper into WebSphere on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers