IBM WebSphere Developer Technical Journal : A guided tour of WebSphere Integration Developer -- Part 7

Interface and Business Object Mapping and Human Tasks

This is the seventh article in a series that explores a service-oriented approach to application integration using IBM® WebSphere® Integration Developer. The previous articles took you through a scenic tour of the product, helped you build an application, and showed you some of the main tools to develop your service-oriented applications. This article takes you deeper into more tools in the suite: for interface and business object mapping, and human tasks.

Richard Gregory (gregoryr@ca.ibm.com), Staff Software Developer, IBM

Photo of Richard GregoryRichard Gregory is a software developer at the IBM Toronto Lab on the WebSphere Integration Developer team. His responsibilities include working on the evolution and delivery of test tools for WebSphere Integration Developer.



Randy Giffen (Randy_Giffen@ca.ibm.com), Senior Software Developer, IBM

Photo of Randy Giffen Randy Giffen is a senior software developer is the usability lead for WebSphere Integration Developer and WebSphere Message Broker Toolkit. He was responsible for WebSphere Integration Developer's business state machine tools and the visual snippet editor. Prior to to this he was a member of user interface teams for WebSphere Studio Application Developer Integration Edition, Eclipse, and VisualAge for Java.



Jane Fung (jcyfung@ca.ibm.com), Advisory Software Developer, IBM

Photo of Jane Fung Jane Fung is an Advisory Software Developer at IBM Canada Ltd, where she is responsible for developing the Business Process Execution Language (BPEL) and Business Rules debuggers in WebSphere Integration Developer. Prior to that, she was the team lead of the WebSphere Studio Technical Support team.



Greg Adams (Greg_Adams@ca.ibm.com), Distinguished Engineer, IBM

Photo of Greg AdamsGreg Adams was the lead architect for the user interface in the award-winning Eclipse platform, and more recently, has been the lead architect and development lead in the core WebSphere Business Integration Tools, including WebSphere Studio Application Developer Integration Edition and WebSphere Integration Developer. Greg led the delivery of IBM's first complete services oriented architecture (SOA) tools stack and the first BPEL4WS standards supporting Business Process Editor; both critical deliverables in support of IBM's On Demand strategy.



25 October 2006

Also available in Chinese

From the IBM WebSphere Developer Technical Journal.

Introduction

In the previous articles in this series, you learned how to implement your service components using business processes and state machines. Then you learned how to respond quickly to changing business conditions by implementing other components with business rules and selectors, both of which let you change parameters after you deploy an application. In this article, we’ll look at more of the supporting features in WebSphere Integration Developer.

One challenge is sure to arise in a service-oriented application: what happens when two services need to work well together, but they don’t understand how to communicate? Early on in this series, we explained that a component implementation calls another component using a reference. We pointed out that the interface of a reference must match the interface of the component to which it is wired. However, what if the interfaces don’t match?

For example, suppose a reference’s interface has a retrieveCustomerData operation and the component to which you want to wire that reference has an interface with a getCustomerData operation. Looking a bit deeper, the problem compounds if one of the business objects that the getCustomerData operation returns has a field called custId, but the retrieveCustomerData operation expects the return parameter name to be just id.

In a small, localized application, the solution is quick: just change the interfaces so that everything matches. In practice though, your business partners often provide interfaces for services that you use, for example Web Service Definition Language (WSDL) files, so changing them is out of your control. Even if you could change the interface, it might break existing consumers of the service. On the client side, changing the interface of the reference might also be out of the question because you would have to change the implementation to use different names. WebSphere Integration Developer makes it very easy to get around this obstacle: it lets you create interface and business object maps.

If you’ve ever tried to wire a reference to a component where there was a mismatch between the interfaces, a dialog box would have opened asking if you wish to create an interface map. This article will show you how easy it is to create different types of maps.

In addition to mapping, we will also explore human tasks. Automating business processes is essential to a company’s efficiency and effectiveness. However, quite often, a business process still requires human intervention. For example, a bank loan approval process might require an experienced loan specialist to evaluate borderline loan applications. A retail store process that automatically re-orders inventory when the inventory level falls below a certain limit might require the store manager to approve all the orders with a large dollar value. Human intervention might also be required in dealing with exceptional cases during a business process. In situations similar to these, you can use a human task component when designing integration applications

A human task, as the name suggests, is a task that involves a human. It is a component in a module just like the others we have seen, such as a business process, business state machine or business rules. You might wonder what the difference is between the staff activity in WebSphere Studio Application Developer Integration Edition, Version 5.1 and a human task component. You could only use a staff activity from within a business process, and its functionality was limited. For example, a staff activity did not allow escalations (an automatic reassigning of a task that has not been claimed or completed). In Version 6, a human task is a first-class component and is no longer restricted to being an internal activity in a business process. Furthermore, a human task component not only allows the computer to interact with a human, but it also allows human-to-computer and human-to-human interactions.

After we explain human tasks, interface maps, and business object maps, we will let you get your hands dirty again, this time by creating a human task with a mapping that enables two components with different interfaces to communicate with each other.

In the following sections, you will learn how to perform more tasks using WebSphere Integration Developer:

  • Mapping interfaces and parameters
  • Mapping business objects
  • Implementing components as human tasks
  • Creating your own human tasks
  • Creating your own interface and business object maps

Interface maps

An interface map sits between two components with different interfaces and lets you say, "When I call OperationX of InterfaceA, send the request to OperationY of InterfaceB." Of course, the parameters of both operations might not match either. So, an interface map also lets you say, "Pass the value of Parameter1 of OperationX to Parameter2 of OperationY." If the parameters of both operations are of the same type, then that’s all there is to an interface map. Often, however, the parameter types are different. In the Parameter Mapping section, we'll show you the various mapping tools that help you when parameter types are different.

For example, suppose an order-processing component needs to call the shipOrder operation of a shipping component. However, the interface for the shipping component has an operation called ship, and both operations have different names for their parameters. Figure 1 shows two interfaces: one containing the shipOrder operation and the other containing the ship operation. Notice that the parameter names of each operation are different. Figure 2 shows you an interface map that resolves these differences.

Figure 1. Two operations that require a map
Two operations that require a map
Figure 2. An interface map
An interface map

At the top of the interface mapping editor, you connect operations of the interface on the left to operations of the interface on the right. For the operation parameters, the bottom of the editor shows mappings that you create by connecting the respective parameters (inputs and outputs) of each operation. A move mapping type is created by default when you connect parameters. We'll discuss the different types of parameter mappings shortly.

The map type is pointed at one end to indicate the direction of the mapping. For example, the upper move indicates that the orderInfo input value gets passed to the order parameter, while the lower move indicates that the value of the output parameter ok gets passed to the shipped parameter.

There are two ways to create an interface map. The first way is to use the interface map wizard (File - NewInterfaceMap), as Figure 3 shows. With this method, you select or create the source and target interfaces. The source interface is the interface that belongs to a reference of a component and the target interface belongs to the component being called from the reference.

Figure 3. New Interface Map wizard
New Interface Map wizard

The other way to create an interface map is to wire a reference of one component to another component. You use this method when the reference and component have different interfaces. The assembly editor asks you if you want to create an interface mapping between the source and target nodes (the nodes being the reference and the component, respectively).

Operation mapping

After you have created an interface map, you need to define the mapping between the interface operations, as you can see at the top of Figure 4. You create a mapping by clicking next to an operation on the left and dragging the end of the connection to the corresponding interface on the right. When you select the connection between two operations, the parameter mappings display in the lower half of the editor. The next step is to draw connections between equivalent parameters.

Figure 4. Creating an interface map
Creating an interface map

Parameter mapping

After you have specified which operation of one interface corresponds to which operation of another interface, you need to map the operation parameters. As with an operation map, you connect inputs and outputs of one operation to the corresponding inputs and outputs of another operation. However, mapping corresponding operations requires only a line between them, while mapping data can be more complex. If the parameter types match, then you just connect the corresponding inputs or outputs as Figure 4 shows. Often, the types will not match, but the business object map editor helps you to map the data as we'll show you in the Business object maps section.

First, let's look at how you create a parameter mapping. For input parameter mappings, you drag a connection from an input parameter on the left to the corresponding input parameter on the right. For output parameter mappings, you drag the connection from right to left. After creating the mapping, the next step is to specify the type of map. You can select from a list of mapping types in the Description tab of the Properties view. In the sections that follow, we will explain the five types of mappings:

  • Move
  • Extract
  • Map
  • Assign
  • Java

Move

By default, when you connect two parameters, the type of map that is created is called a move parameter mapping. In the earlier example, we showed a move parameter mapping. With a move parameter mapping, the exact value of a source parameter will pass as-is to a target parameter. The type of each parameter, whether it is a string or a business object, must be the same. Move mapping types are 1-to-many, which means you can map a source parameter to one or more target parameters.

Extract

Sometimes, a target parameter requires only some of the data from the source parameter. In this case, you can use an extract. An extract parameter mapping takes the value of a business object's attribute, which could be a simple type or a nested business object, and puts it into the target. Figure 5 shows a variation on the earlier example where the ship operation has two input parameters whose types are Item and Address. The Order business object used in the shipOrder operation contains attributes with the same Item and Address types as you see in the XPath tree in the bottom of the figure. The Properties view shows an XPath expression that selects the item attribute from orderInfo. When you use the mapping, the values for orderInfo.item are passed to the item parameter. We use a second extract with orderInfo as the source to transfer the orderInfo.address value to the address parameter.

Figure 5. An extract parameter mapping
An extract parameter mapping

Map

If the parameter types don't match, you use a map instead of a move. A map parameter mapping lets you reconcile different business object parameters. There are numerous mismatches that can exist between two business objects, even though each one contains information that the other needs. A mismatch could occur because the attributes of one business object are in a different order and have different names than the attributes of the other business object. Or a mismatch could get quite complex: one business object might represent a name with three attributes (salutation, firstName, and lastName), while another might represent a name using just one attribute that is meant to hold a comma delimited string. You might even have multiple business objects whose individual parts need to be mapped to or from one business object. When you use a map, you specify a business object map that maps the attributes of one business object to another. The section on business object maps describes this mapping type in detail.

Assign

You can also map a constant value to a target parameter. An assign parameter mapping lets you specify a constant value to put in a target parameter. This type of mapping has only a target. Therefore, to create an assign mapping, you can't create a connection between two parameters and change the type to assign (because a double-ended connection can't be an assign mapping). So, to create an assign mapping, right-click a target parameter (an input on the right or an output on the left) and select Create Transform - Assign. In the Properties view, you can enter the constant value.

You should use an assign mapping when a target operation contains a parameter that is not present in the source operation. The extra parameter might no longer be in use. Because a map requires all targets to have a mapping, you can assign some default value to the extra parameter. The extra parameter could also always have the same value when called from your module. For example, Figure 6 shows a ship operation with an orderType parameter that is not present in the shipOrder operation. The assign mapping passes a value of express each time the map is used.

Figure 6. An assign parameter mapping
An assign parameter mapping

Java parameter mapping

For maps that require custom logic, you can use a Java parameter mapping. A Java parameter mapping lets you write arbitrary Java code to transform one object to another. In the Details section of the Properties view, you specify the name of the class, which must extend the Java class com.ibm.wbiserverspi.mediation.JavaMediation. The JavaMediation class contains a mediate method that takes an object as input, which is the value that is to be mapped, and returns an object that is the transformed value.


Business object maps

In the parameter mapping examples, you saw how to map the parameters between operations using mapping types such as move and extract. In this section, we'll look at what happens when the parameter types are not the same and you can't use a parameter map. As we noted earlier, the map parameter mapping type requires you to specify a business object map that handles the mapping between the attributes of two business objects. In this section, we show you what business object maps are and how to use them.

Transform types

Mapping business object attributes is similar to mapping parameters: you connect source attributes to target attributes. Mapping attributes is also called transforming attributes. Because transforming attributes generally requires more flexibility than mapping parameters, there are more transform types. The next sections will cover the following transform types:

  • Move
  • Submap
  • Extract
  • Assign
  • Custom
  • Join
  • Relationship

Move

A move transform is analogous to the move parameter mapping type. It assigns the value of a primitive-type attribute in the source business object to a primitive-type attribute in a target business object. You can map one primitive-type attribute, such as a string, to another, such as an integer. Keep in mind that if the data cannot be converted at runtime, you get an exception. For example, if the string "123a" is mapped to an integer, you will see a NumberFormatException in the server log. Furthermore, unlike a move parameter mapping, you cannot map complex types using a move transform. For mapping between business objects, you need a submap, as we will describe shortly.

Figure 7. A move transform
A move transform

Submap

A submap is another business object map that you use to transform one business object to another. For example, in Figure 8, the PO business object contains an Address business object. On the right, in Order, there is also an Address in the Customer business object. The Details tab shows that the Address business object map maps Order/customer/address to PO/shipTo. Because the source and target have the same type, Address, the submap consists only of move transforms between parameters with Address attributes. This might remind you of the extract parameter mapping earlier. If the interface containing PO had two parameters, invoiceNum and shipTo, instead of just one PO parameter, we could have used an extract parameter mapping here.

Figure 8. A submap transform
A submap transform

Extract

An extract transform is a bit different than its parameter mapping counterpart because its source attribute must be a string. You use the extract transform to extract parts of a string and assign those parts to another string, or to any other primitive type, with the caveat we mentioned in the move transform section.

For example, Figure 9 shows two extracts that separate the first name and last name from a string with the format lastname, firstname. The details for the second extract show that the part of the name string up to the first comma gets copied to the lastName attribute of the Person object. The substring index determines which section of the string, starting from 0, to use. Therefore, the firstName extract contains the same details as the lastName extract, except that the substring index is 1 (It uses the second part of the string: the characters between the first comma and the second). If the value of the name attribute is "Smith, Joe", then firstName will get a value of "Joe" and lastName will get "Smith".

Figure 9: An extract transform
An extract transform

Join

A join transform combines the values of two or more source attributes and copies them to a target attribute. The target of a join transform must be a string. You can think of a join transform as the inverse of the extract transform because it takes a set of string inputs (or any other primitive type, which will be converted to a string), and joins them into one string, optionally separated by delimiter.

In the extract transform example, we showed mapping a comma-delimited string to separate first and last name attributes. Often you need to map both ways. Figure 10 shows you how to map back from the Person business object to the emp business object. If firstName contains the value "Joe" and lastName contains "Smith", then the name attribute gets the value "Joe,Smith" because firstName has a delimiter set to a comma.

You can check how the join concatenates the values by looking at the example at the bottom of the Details tab. Keep in mind that the delimeter can consist of multiple characters. The Prefix and Postfix fields let you add strings to add a prefix to and append the resulting joined string. You can also use the Reorder icons to change the order in which the attributes are concatenated.

Figure 10: A join transform
A join transform

Assign

An assign transform sets a constant value to a target attribute. Figure 11 shows an assign transform that sets the prefix attribute of Person to null.

Figure 11: An assign transform
An assign transform

Custom, custom assign, and custom callout

To write Java code to specify the mapping logic between a source and a target attribute, you use a custom transform. If there is no source attribute, then you use a custom assign transform, which is similar to an assign transform, except that you use Java code to compute the assigned value. If there is no target attribute, then you use a custom callout transform, to initialize values.

Relationship

You use a relationship transform when the same data has different names or different identities. The relationship transform is different than other mappings because with other mappings we are interested in connecting different attribute names or business objects that refer to the same data. A relationship transform goes one step further by also handling cases where the data is different but has the same meaning or refers to the same thing.

There are two types of relationship transforms: dynamic and static. A static relationship correlates different values that refer to the same thing. These types of values never, or rarely, change. A typical example is a state or province name: one system might use 2-letter designations such as ON, while another might use longer abbreviations such as Ont., and still another, full names such as Ontario.

When you map data from one attribute to another with a static relationship, you can also transform the data according to the table you create with the relationship editor. For example when the province attribute of one business object that has a value of "ON" is mapped to another business object attribute, the value assigned could be "Ontario."

You use a dynamic relationship to correlate data based on primary keys. For example, a product in a store might have one identifier on the inventory tracking system and another on the suppliers system. Your system might have an identifier in a generic business object that not only contains the same data as identifiers in other business objects, but something needs to keep track of which data is actually the same. For example, when itemNumber, which has a value of "123", is mapped to productCode (in a business object used in the supplier's interface), the value of "a234" might need to be inserted so that the correct item will be ordered from the suppliers system. The relationship manager on WebSphere Process Server takes care of this.

The two relationship articles, WebSphere Process Server relationship service, Parts 1 and 2, listed in the references section, take you through exercises that clarify how you would use both types of relationship transforms.

Variables

To store data that you want to reuse, you create variables. A variable can be a source and a target for each of the transform types described earlier. For example, if you have a value that you want to assign to many targets, you can use an assign to set a value to the variable, then use a move transform from that variable to multiple attributes.

As an example, Figure 12 shows a map with a variable named code that is populated with the value of orderInfo.code. This value is used in orderItems.code and shipTo.code. Note that for this to work, the execution order (indicated by the number on the left of the transform type) of the assign to the variable must be lower than the targets to which the variable is mapped. Otherwise, the variable will be uninitialized when it is used.

Figure 12: Using variables
Using variables

Human tasks

WebSphere Integration Developer helps you develop solutions that allow different computer applications to work with each other. However, developing an integrated information system often involves supporting interactions with humans.

Human involvement takes several forms. For example, a person might be required to initiate a process instance that can then proceed on its own. A person might be required to deal with exceptional cases that the logic built into the application cannot handle, perhaps because the case is considered too complex or special. A case might also require human intervention because the normal processing has failed for some reason.

Having decided that a process should involve a human, developers are faced with the decision of how to implement this functionality. WebSphere Integration Developer provides a human task component, which greatly simplifies the work required to support human interaction with an SCA application.

A scenario for the involvement of a human in a service-oriented application is a process that requires a decision from a person to approve an order before proceeding, as shown in Figure 13.

Figure 13: A decision made by a human within a process
A decision made by a human within a process

Consider some of the requirements for the scenario:

  • A mechanism to get data to and from the user
  • To be asynchronous and long running (because the human might not be able to respond immediately)
  • An interface to enable the interaction. Since more than one process instance might require human involvement at any one time, the user interface needs to show the processes waiting for input and it needs to provide the details of a selected task
  • A way to verify that the user has the right to perform the task

A human task satisfies these requirements, and provides a stand-alone component just like business processes and business state machines. It communicates with other components using interfaces and business objects. Figure 14 shows a human task component called ApprovalHumanTask, that the process shown in Figure 13 calls.

Figure 14: A human task component
A human task component

However, human task components are unique because they support only a single interface that might have only a single operation. This reflects the fact that a human task defines only a single interaction, multiple interactions require multiple human tasks. Let's consider a file folder analogy. The folder contains information required to identify and complete the task. The user adds any required comments or data to the contents of the folder and returns it.

Human tasks are inherently asynchronous and long running. It would not be realistic to assume that a human can process all requests immediately. Rather, tasks requiring human intervention must be managed on a queue for completion when a human is available. Using our file folder analogy, imagine an inbox with a stack of file folders waiting to be processed. Each will remain in the inbox until it can be processed and re-filed.

Types of human tasks

There are three types of human tasks, which we will look at in the next sections:

  • Participating
  • Originating
  • Pure

Participating human tasks

In a participating human task, a component, such as the OrderProcessing component in Figure 14, calls a human task component. In other words, the human task participates in getting work done.

Figure 15: A participating human task
A participating human task

Originating human tasks

An originating human task calls another component. Instead of being assigned work, it begins the process of getting work done. An originating human task represents a human requesting something rather than fulfilling a request.

Figure 16: An originating human task
An originating human task

Pure human tasks

A pure human task is similar to an originating human task because a human requests it. However, with a pure human task, another human rather than a computer application fulfills the service request. In this case, the application mediates interaction between humans.

Figure 17: A pure human task
A pure human task

Creating a human task

To add a human task to a module, select File - New - Human Task. The New Human Task wizard lets you specify a name and container for the task. The second and third pages of the wizard let you indicate the kind of task you want to create and specify its interface. The human task editor then opens for the newly created task.

Now let's look at how you can configure human tasks.

Staff settings – roles

As you can imagine, you need a way to associate a human task with a specific person or any member of a group of people who is qualified and permitted to complete the task. You can also assign roles (for example, Potential Owner, Reader) to a human task so that specific access rights can be granted.

Figure 18: Staff settings
Staff settings

Client settings

WebSphere Process Server includes a built-in Web-based user interface, the Business Process Choreographer (BPC) Explorer, for human tasks. This interface is suitable for testing and administration purposes, but it is not meant to be used as a user interface for human tasks in a real-world application. The developer should develop a custom user interface to display the contents of the task and allow the user to work on it.

WebSphere Integration Developer includes built-in support for two kinds of user interface implementations, but you can add others via extensions. The supported user interface types are JSPs and portlets. In the client settings area of the editor, you can select the kind of interface to supply and, in the details area, specify where the interface implementation is located. References at the end of the article offer specific details about implementing a custom interface.

Figure 19: Client settings
Client settings

Escalation settings

When a user claims a task, the intention is to complete it within a reasonable period of time. However, there are often circumstances that prevent timely completion. For example, the user might be waiting for additional material before making a decision. What happens if the process that is calling the task might require a response within a certain period? In response to such cases, a human task allows the developer to specify an escalation to occur if a task is not claimed or completed within a certain period.

When a human task is invoked, it is either in the ready (not yet claimed) or the claimed state. Escalations are like timers in a business state machine. When a task has entered a state, the escalation will trigger and carry out its specified action if the task does not leave the state by the time specified in the escalation. You can specify a series of escalations where each one is triggered as soon as a duration expires and while the task remains in the particular state.

Another state for a human task is the subtask state. When a user claims a task, the user can delegate a portion of task to another user, which puts the human task in the subtask state. You can add escalations to the subtask state to ensure that this portion of the task is completed so that the overall task can proceed.

Figure 20 shows a human task that will send a notification if the task is not finished within two hours. The Verb tab contains the name of the person who will be notified if the escalation occurs. In the following sections we will explore escalations in the application you will build. The references at the end of the article also offer more information on using the Human Task manager and developing your own client to assign subtasks and respond to escalations.

Figure 20: Escalation settings
Escalation settings

Inline human tasks

Rather than existing as an individual component, an inline human task, which is another form of a participating human task, is defined inside a business process. It is only accessible from within the process. One advantage of this human task is that it can access the context of the process (for example, processes variables), allowing multiple human tasks within the process to share information.

Figure 21: An inline human task
An inline human task

Putting it all together

To understand how to map interfaces and business objects and invoke a human task, we'll take you through the process of mapping two interfaces and then show you how to request a human task from a process. In the first scenario, suppose you have an order-processing system and a business partner who handles the shipping. To ship items, you use your partner's Web service. Unfortunately, the format is not compatible with your partner's Web service input even though the Order business object that is used in your module contains enough information to ship an order. For example, the Order business object contains a CustomerInfo business object and a list of Item objects as Figure 22 shows.

Figure 22: The OrderProcessing business object and its contents
The OrderProcessing business object and its contents

Figure 23 shows the business objects expected in the Web service interface. The interfaces that use these business objects also don't match as Figure 24 shows.

Figure 23: The ShippingService business objects
The ShippingService business objects
Figure 24: The placeOrder and shipOrder interfaces
The placeOrder and shipOrder interfaces

In our scenario, an order must be approved by an employee before it can be shipped. If the task is not completed within a certain time, then it is escalated. For the purpose of illustration, we will just use the defaults which allow anyone to claim the task or handle the escalation.

The project interchange file (in the downloads section at the end of this article) contains a module with an order-processing component. The component is implemented with a business process and has ApproveOrder and ShippingPartner references with ApproveOrder and Shipping interfaces. There is also a library that contains the ShippingService WSDL file that accesses your partner's Web service.

In the Business Integration view, the contents of the WSDL file (which is the interface to the Web service) display as any other interface. For example, the parameter types (the WSDL message parts), display as business objects. In addition, there is an import with the ShippingService interface that you can use to call the Web service.

Let's start by importing the project interchange file that contains the supporting components, interfaces, and business objects:

  1. Download the mappingexamplebegin.zip file from the Downloads section at the end of the article.
  2. Click File - Import - Project Interchange, and then click Next.
  3. Click Browse, browse to the mappingexamplebegin.zip file that you just downloaded, and click Open. This zip file is the project interchange file.
  4. Check Select All, and then click Finish. The imported modules open in the Business Integration view and, as the project builds, you see a Building workspace message in the lower right corner of the workbench. Wait for the workspace to finish building.

Implementing human tasks

Now that the workspace is built, you need to use the new human task wizard to create a human task to implement the ApproveOrder interface.

  1. Under the MappingExample project , right-click the Business Logic category and select New - Human Task.
  2. Enter ApprovalHumanTask for the name, and add it to the MappingExample module. Then click Next.
  3. Leave the default setting as Participating Human Task, and then click Next.
  4. Ensure Select an existing Interface is selected, and then choose ApproveOrder for the interface, and click Finish.

The Human Task editor opens for ApprovalHumanTask. Now you can set the necessary properties for it

  1. Under the Client settings section, right-click Client settings and select Add - BPC Explorer.
  2. Under the Escalation section, right-click Claimed and then select Add - Escalation.
  3. In the Details tab of the Properties for the escalation, ensure that Finished is selected for the Expected task state, and enter 2mins for the Duration until escalated.
  4. Save the editor contents.

The next steps allow the OrderProcessing component to reference the new human task.

  1. Double click MappingExample - Mapping example to open the assembly editor.
  2. Select ApprovalHumanTask under the Human Tasks category and drag it to the assembly diagram.
  3. Wire the OrderApprovalPartner reference of the OrderProcessing component to ApprovalHumanTask as Figure 25 shows.
    Figure 25: MappingExample assembly diagram
    MappingExample assembly diagram

Creating an interface map

Looking at the assembly diagram in Figure 25 , you see that you need to wire the OrderProcessing reference to the Shipping service import because OrderProcessing should call ShippingService. Let's see what happens when we try to create a wire when the source and target interfaces don't match:

  1. Hover your mouse over the reference on the right of the OrderProcessing component.
  2. Drag the handle that appears to the ShippingService component. The Add Wire dialog box opens.

The assembly editor detects that you are trying to wire a source to a target whose interfaces are different. The Add Wire dialog box, which you see in Figure 26, opens so that you can choose to create an interface mapping or add the appropriate interface to the import. The next steps help you start creating the interface map.

Figure 26: Wiring components in the MappingExample assembly diagram
Wiring components in the MappingExample assembly diagram
  1. To close the Add Wire dialog box, click OK. This step creates a new interface map, as shown in Figure 27.
  2. Double-click OrderProcessingToShippingServiceMap to open the interface mapping editor.
Figure 27: An interface map between two components
An interface map between two components

The next steps help you define the mapping between the OrderProcessing and ShippingService interfaces:

  1. Hover your mouse over the placeOrder operation interface (shown in Figure 28) in the interface mapping editor, and then drag the handle that appears to the shipOrder operation.
  2. Click the connection that is created between the two interfaces to display the parameters of each interface.
  3. Hover your mouse over the order parameter and connect the handle to the shipTo parameter

You have just created a mapping between the order and the shipTo parameters. By default, it is a move mapping type. However, we need a business object map so that we can map the attributes of the order parameter to the shipTo and orderInfo parameters.

  1. Hover over the move map type and drag the handle to the orderInfo parameter.
  2. Select the move type mapping and open the Description tab in the Properties view.
  3. Change the Parameter Mapping Type to map.
  4. In the same manner, connect the orderNumber parameter in the shipOrder operation to the orderNumber parameter in the placeOrder operation. Leave move as the map type.
  5. Save the editor contents.
Figure 28: The OrderProcessingToShippingServiceMap interface map
The OrderProcessingToShippingServiceMap interface map

Your interface map should now look similar to the one shown in Figure 28. There is a red ‘X' in the map connection because there is no business object map defined yet. The next steps will create the business object map.

Creating a business object map

  1. Select the Details tab in the Properties view for the map, and then click New next to Business Object Map.
  2. In the New Business Object Map dialog box that opens,enter PlaceOrderToShipOrderMap for the Name, and then click Next.
  3. Ensure that the Order business object is selected for the inputs and that destination and order are selected for the outputs as Figure 29 shows. These types correspond to each parameter at the source (inputs) and target (outputs) that you chose for the mapping.
Figure 29: Creating a new business object map
Creating a new business object map
  1. Click Finish.
  2. PlaceOrderToShipOrderMap should appear as the setting for Business Object Map. If it does not, save and close the interface editor, then reopen it and select PlaceOrderToShipOrderMap from the list.
Figure 30: Setting the business object map
Setting the business object map

At this point you have created an empty business object map so you can map the Order business object to the Destination and Order business objects. By following the next steps, you will create the mappings between the various business object attributes.

  1. Double-click the map type mapping in the interface map editor to open the business object map editor for the map if it is not already open.
  2. In the business object map editor, connect items in the Order business object on the left to items in the order business object on the right. A submap transform is automatically created because both items are business objects.
  3. In the Details tab of the Properties view for the submap transform, click New next to business object map, enter ItemsMap for the name, and then click Next.
  4. Ensure Item (with namespace http://MappingExample/) is selected for the inputs, and that item (with namespace http://e.z.orders.com/) is selected for outputs.
  5. Click Finish.
  6. In the business object map editor that opens for ItemsMap, connect the attributes as shown in Figure 31.
  7. Save the submap editor contents and switch back to the PlaceOrderToShipOrderMap editor.
Figure 31: The ItemsMap business object map
The ItemsMap business object map

You have just implemented the submap transform that is shown in Figure 32. Next, we'll map the attributes that contain the destination information:

  1. Connect firstName and lastName from the Order business object on the left to firstname and lastname respectively in destination on the right (first expand customerInfo if it is not already expanded).
  2. Connect street, city, state, and zip from Order on the left to address in destination on the right. You have four source attributes mapped to one target attribute.
Figure 32: Business object mapping
Business object mapping

Your map should now look like the one in Figure 32. Notice that when you connect many attributes to one target attribute, the editor creates a join transform and redirects all the targets as inputs to the join (you could also have connected the source attributes directly to the join).

For large business objects, a map quickly becomes very complex, making it hard to tell which attribute is mapped to which. The business object mapping editor can help by providing you with different views of the map. In Figure 32, where the transforms are sorted by target, it's getting hard to follow the source of the transforms, so Figure 33 shows how the map looks when the transforms are sorted by source.

Figure 33: A business object transform sorted by source
A business object transform sorted by source

The next step is to tweak what happens with the four attributes when you merge them into the address attribute:

  1. Open the property details for the join transform.
  2. Enter ", " (comma and space, without the quotes) as the delimiter for street, city, and state. Notice that the example updates to show you how the merged attributes will look as you add delimiters, as the bottom of Figure 34 shows.
Figure 34: Join details
Join details

You are finished. Now you can test your application with these last few steps:

Testing the application

  1. Switch back to the assembly editor for MappingExample, and select the OrderProcessing, ApprovalHumanTask, and OrderProcessingToShippingServiceMap components (after selecting OrderProcessing, hold down the Ctrl key while clicking ApprovalHumanTask and OrderProcessingToShippingServiceMap).
  2. Right-click any of the selected components and select Test Components. This open the integration test client. Because ShippingService was not selected to be tested, it will be emulated. (The Web service described by the ShippingService WSDL file doesn't actually exist. You might want to experiment with the tools and create it.). If you switch to the Configuration tab at the bottom of the test client, you will see ShippingService listed under Emulators.
  3. Ensure OrderProcessing is selected for the component name.
  4. Add an Item business object to the list of items for the order by right-clicking the items row in the Initial request parameters section, and selecting Add Element.
  5. For each of the value fields, enter any values, such as those in Figure 35, and click Continue.
  6. When prompted to select a deployment location, choose any WebSphere Process Server, and click OK.
Figure 35: Testing the mapping application
Testing the mapping application

The application deploys to the server. Eventually the process stops at the invocation of the human task.

Figure 36: Waiting for human task approval
Waiting for human task approval
  1. Select the server in the Server view and, from the Launch context menu, select Launch BPC Explorer.
  2. Click My Tasks. The task list shows your task waiting to be completed, as Figure 37 shows. Check the box next to the task and click Work on to claim the task.
    Figure 37: List of task instances waiting to be claimed
    List of task instances waiting to be claimed
  3. Rather than clicking Complete under Available actions for the task, as Figure 38 shows, just wait for two minutes to pass to trigger the escalation.
    Figure 38. Completing the task
    Completing the task

The task is now in the claimed state and will stay there until either the escalation, or the original task completes. Because you have set the duration until escalated time for the task to move from the claimed to finished state to two minutes, after two minutes elapses, you see the task in the escalations list

  1. On the left side of the BPC Explorer, click My Escalations.
  2. Click ApprovalHumanTask, and then click Work on. The same page displays as in
  3. Click Complete.

The task then appears, showing the input data, and waits for your input. To return the default value of true click Complete.

Eventually you will be prompted to enter a value for the output parameter of the ShippingService import (it is being emulated). Notice that the information you entered in the previous steps has been mapped to the shipTo and orderInfo parameters as Figure 39 shows. To complete the process, enter any value for orderNumber, and then click Continue. The orderNumber parameter of the ShippingService interface is mapped back to the orderNumber parameter of the OrderProcessing interface.

Figure 39. Emulating the ShippingService import
Emulating the ShippingService import

Conclusion

Human tasks, interface maps, and business object maps are useful complements to the various component types available with WebSphere Integration Developer. In this article, we introduced you to the main concepts of human tasks and the different types of maps and showed you how to use them in your order processing application.


Downloads

DescriptionNameSize
MappingExample modulemappingexamplebegin.zip  ( HTTP | FTP )15 KB
Complete MappingExample modulemappingexamplecomplete.zip  ( HTTP | FTP )19 KB

Resources

Learn

Get products and technologies

Discuss

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 Business process management on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Business process management, WebSphere, SOA and web services
ArticleID=169739
ArticleTitle= IBM WebSphere Developer Technical Journal : A guided tour of WebSphere Integration Developer -- Part 7
publish-date=10252006