DATA AND INTERFACE MAPS IN A BUSINESS PROCESS

INTRODUCTION

A business process forms the heart of data integration between disparate software systems. In real life, different systems represent similar data (such as Product and Customer) in different ways. The best practice is to follow the Canonical Data Model pattern. This pattern simplifies business process development. The process itself works with a generic data format. When an external system sends data to the process in the system’s native format, a data map is applied to convert the data to the generic (or canonical) format. When data is sent by the process to another external system, another map can be applied to convert the canonical format to the native format of that system.

Interface map is a related concept. Consider a business that manufactures automobile tires. When a new brand of tire becomes available, the company needs to notify all dealers. Now, the dealers sell tires from many different manufacturers. It is difficult for a dealer to provide a service implementation that satisfies the specification requested by all manufacturers. Chances are that a dealer will implement a service that either follows their own specification or the specification of one of its preferred manufacturers. In a situation like this, the business process that notifies all dealers should use a generic interface to represent each dealer. An interface map needs to be applied between the generic interface and the native interface of a specific dealer. The interface map will translate operation name differences as well as parameter data format differences. The later is accomplished using data maps that we have already discussed. As a result, data maps are always used in conjunction with interface maps.

In various IBM documentation, the business objects following the canonical format are called Generic Business Objects (or GBOs). The native business objects are called Application Specific Business Objects (or ASBOs).

BUSINESS LOGIC

In this tutorial, we will model the tire manufacturer to dealer communication scenario described above. A new business process called PropagateProductAvailability will be created. It will accept as input a Product GBO business object. The process will then invoke a service for each dealer. The invoked service will follow the generic interface ProductMaintenance. Later, an interface map will be applied. This will also contain a data map that will convert the Product GBO to dealer specific object.

To keep things simple, we will create only one dealer service. The design will allow us to add new dealers quite easily.

DEVELOP THE PROCESS

You should be familiar with basic process development by now. If not, go through some of the previous tutorials first.

Create a new business integration module called SimpleModule unless it is already created.

Create a new business object called Product in the types folder. Add a few attributes as shown below.

Create a new interface called IPropagateProductAvailability in the interfaces folder. The business process will implement this interface. Add a one way operation called start. Add a single input called product of type Product.

Save changes. Close all open editors.

Create another interface called ProductMaintenance in the interfaces folder. This is the generic interface for all dealers. To the interface, add a one way operation called notifyNewProduct. Add a single input called product of type Product.

That is all we need to design the process. Create a new process called PropagateProductAvailability in the procs folder. Make the process implement the IPropagateProductAvailability interface.

Add a snippet activity below the receive activity. We will print out a few debugging statement there. Set the code for the snippet to as shown below.

System.out.println("Announcing new product: " +
 	Product.getString("SKU")); 
System.out.println("Short description: " +
 	Product.getString("ShortDescription"));

Add a new reference partner called acmeDealer.

While the new reference partner is selected, activate the Properties view. Click on the Details tab. Next to ReferenceInterface drop down, click on Browse and select ProductMaintenance. Similarly, we could easily add other dealer references. Because, we treat each dealer the same way, the process becomes easy to develop and maintain.

Below the snippet activity add an invoke activity. Change the name of the activity to Notify Acme.

While the invoke activity is selected, go the Properties view. Set the Partner to acmeDealer. System should automatically select the notifyNewProduct operation (as it’s the only operation available). Associate the Product process variable to the product input parameter for the process.

Save changes. The process design is complete.

IMPLEMENT THE ACME DEALERSHIP SERVICE

In a previous tutorial, we learned how to implement a service as a web service. In this tutorial, we will keep things simple and build the service as a plain Java class.

Acme dealership models a product as the AcmeProduct business object. This is an ASBO. Create a new business object by that name in the types folder. Add a few attributes as shown below.

Save changes. Note that the AcmeProduct object represents the same entity as the Product object but in a slightly different way. Later we will define a map between the two.

The Acme dealer’s service conforms to its own proprietary interface called AcmeProductManagement. Create a new interface in the interfaces folder by that name. Add a one way operation to the interface called addNewProduct. Add two inputs to that operation as follows.

manufacturerID of type string. This identifies the manufacturer who is sending the notification.
product of type AcmeProduct.

Save and close the interface editor.

Now we will create a Java implementation of the AcmeProductManagement interface. Double click on SimpleModule->SimpleModule to open the assembly editor. Drag and drop the AcmeProductManagement interface on the editor. Select Component with no Implementation Type. Change the name of the component to AcmeProductManagement. At this point the component effectively represents the abstract interface AcmeProductManagement. Now, right click on it and select Generate Implementation Java. System will prompt you to select the package where the Java class will be created. Create a new package called com.acme.services. Select the package and click on OK.

System will create the AcmeProductManagementImpl class and open it in the editor. Locate the addNewProduct method. The method receives the product object as a generic SDO class DataObject. But, we know that the object conforms to the AcmeProduct schema. Add the following code in the method.

public void addNewProduct(String manufacturerID, DataObject product) {
 System.out.println("Received new product notification from: " +
 manufacturerID); 	
 System.out.println("Product ID: " +
 product.getString("ProductID"));
}

Save changes and close the class. Save the assembly editor. Notice that the AcmeProductManagement component now has a J icon indicating that it is a Java component.

Where are we now? The business process has a partner reference that is expected to implement the ProductMaintennace interface. We have an actual implementation of a service from the Acme dealership that implements the AcmeProductManagement interface instead. We need to build an interface map between the two.

DESIGN THE INTERFACE AND DATA MAP

First we will define a data map between the Product and AcmeProduct objects. Maps are unidirectional. That means a separate map will be required if wished to convert an AcmeProduct object to Product. We will not need that for this tutorial as the dealerships never send any data back to the process.

Expand SimpleModule->Mapping. Right click on Data Maps and select New->Business Object Map. Enter maps in the Folder text box. As the name for the map, enter Product_To_AcmeProduct. Click on Next. From the Inputs list select Product. From the Outputs list select AcmeProduct. Click on Finish.

Drag the SKU attribute of the Product object and drop it on the ProductID attribute of the AcmeProduct object. This will add a simple Move (or copy) transformation rule between the two attributes.

Now, notice that the AcmeProduct object has a single attribute for description. We should merge the ShortDescription and LongDescription field of the Product object into the Description attribute of AcmeProduct. This is easy to do. First, drag ShortDescription and drop it on Description. Then do the same with LongDescription. System will automatically set up a Join rule.

Drag the Price attribute from the Product object and drop it on the Price attribute of AcmeProduct. The currency information is not available from the Product object. It is assumed to be USD. The AcmeProduct object expects the currency information. We will need to hard code this value. Right click on Currency and select Create Transform->Assign.

Select the Assign rule. In the Properties view select the Details tab. Make sure that User defined value is selected. Enter USD as the value. Save changes. The data map is complete.

Now, we will create a map between the two interfaces – ProductMaintenance and AcmeProductManagement. Expand SimpleModule->Mapping. Right click on Interface Maps and select New->Interface Map. Enter maps as the folder name. As the name of the map, enter ProductMaintenance_To_AcmeProductManagement. click on Next. As the source interface, select ProductMaintenance. As the target interface, select AcmeProductManagement. Click on Finish.

System will create the map and open it in the interface map editor. First, we will map the operation name. Drag the notifyNewProduct operation and drop it on addNewProduct. System will show the map as an arrow going from left to right. Select the arrow. System will show the parameters required by these two operations. The manufacturerID parameter required by the addNewProduct operation is not available anywhere from any information received by the notifyNewProduct operation. Fortunately, the business ID of the tire manufacturer does not change often and can be treated as a constant. Right click on manufacturerID and select Assign Constant Value. Select the Assign rule. From the Properties view, set the constant value to 000001.

Now drag the product parameter from notifyNewProduct and drop it on the product parameter of addNewProduct. System will apply a move rule by default. A simple move or copy rule is invalid between two different data types. Select the Move rule. From the Properties view, change the Parameter Mapping Type to map. Now, we have to specify which map should be applied here. This is done from the Advanced tab of the Properties view. This tab is hidden by default. Click on the map rule in the map editor. System will refresh the Properties view and show the Advanced tab. Select the tab. From the Business Object Map drop down, select Product_To_AcmeProduct.

Save changes. Wait for the build to end. Make sure that there are no error messages in the Problems view. Close all open editors.

APPLY THE MAP

A map is applied between a reference partner and an implementation. The reference partner uses a generic interface. The implementation uses an application specific native interface.

Open the assembly editor. The implementation – the AcmeProductManagement Java component is already there. Now, drag and drop the PropagateProductAvailability business process. The little rectangle in the process containing the text 1..1 represents the reference partner acmeDealer.

Drag and drop the ProductMaintenance_To_AcmeProductManagement interface map on the assembly editor.

Follow the sequence of clicks shown above and complete the wiring.

Select the wire tool
Click on the reference partner (1…1) of the PropagateProductAvailability process.
Click on the source interface (I) icon of the ProductMaintenance_To_AcmeProductManagement interface map.
Click on the reference partner of the interface map (1…1). This represents the target interface.
Click on the interface icon (I) of the AcmeProductManagement Java component.

Save changes. The meaning of the above diagram should be very clear to you. When the PropagateProductAvailability process invokes any operation using the acmeDealer reference partner, system takes these actions:

Determines the actual operation name to be called of the AcmeProductManagement interface by using the interface map.
Builds the parameter data by applying the data map.
Finally invokes the operation in the Java component implementation.

TEST THE PROCESS

Clean the projects (Project->Clean from the menubar). Wait for the build process to end.

Start the server. Add the SimpleModuleApp to the server unless it has been already done.

Publish all projects to the server (right click on the server and select Publish). If it fails, you will need to clean the projects and try to publish again.

In the assembly editor, right click anywhere in the white area and select Test Module. (Note: Do not right click on a component and select Test Component). System will open the unit test tool. Select the PropagateProductAvailability component, IPropagateProductAvailability interface and the start method.

Enter some values in the input parameter area as shown above. Then click on Continue. If you get an exception error message shown in the test client, close the client, clean the projects, publish them in the server and try testing again.

The Console view should show the various System.out.println out puts from the process.

O Announcing new product: PR1234 
O Short description: Light Bulb.

Then comes the output from the AcmeProductManagement implementation.

O Received new product notification from: 000001 
O Product ID: PR1234

SOLUTION

All finished projects used by this tutorial can be downloaded as a project interchanged format.

SUMMARY

In summary, we learned the following topics in this tutorial.

The need for interface and data map. In real life, the service provider and consumer may not always agree on the service specification. Interface and data map can solve this problem. Note, how the map is applied outside of the process. That is, an existing process does not have to be changed if an invoke service changes its specification.
How to design a data map.
How to design an interface map and use data maps to map various parameters supplied to the operations.
The best practice is designing a process is to always use generic (canonical) data model and interface. Partner specific interface and data can be different. Maps are there to bridge the gap.
How to apply an interface map between a partner reference of a process and an implementation of a service. The assembly diagram makes the job easy through visual drag and drop. The resulting diagram is easy to understand and maintain.

Using Data And Interface Maps In A Business Process Tutorial