It’s Store-and-Forward, Jim, but not as we know it.

You might have heard of v7 formal support for store-and-fwd and wondering what this post is about. Well, it’s not about v7’s support for it.

The product feature relates to its ability to recognise when a target system is unavailable, work upstream until it finds the first asynchronous interaction point, and start storing requests until human intervention via a dedicated Business Space widget to reopen the information flow.

The key points here are 1) only asynchronous interactions are supported 2) human intervention is necessary to restore the flow.

I’m working against a different scenario here. What I want to do is to automatically switch from synchronous to asynchronous processing of selected interactions when a target system is not available. I want synchronous consumers of my service to always get a synchronous response, either complete or partial, depending on whether my respective target systems are reachable or not.

I also want a retry mechanism that will continue accepting requests and process them all ‘offline’ once the failed external system is restored.

And I want the business process to pick up where it left off and carry on with its activity sequence.

So, imagine you apply for a credit card online, and there are 3 key steps to process your application. First we score your risk, then we validate your application and last we fulfill your order.

You can write a short running BPEL process to orchestrate those three services and give the web front end a synchronous response.

Now, suppose risk scoring is a third party service that’s notorious for being down for housekeeping a few hours every day.

Clearly we can’t fulfill your application without having scored your risk, but neither we want to just tell you to come back later, much later, and that we are sorry but you just wasted your time filling up a form.

What we want is to tell you that your application has been received, it is being processed, and you can look forward to your new credit card arriving in the post real soon (or if you haven’t qualified, a communication to that effect).

So, lets look at a simple prototype of the short running process, without any store and forward capabilities.

Not a lot going on here. We receive a credit card application request, we prepare requests to a number of external systems, we invoke them in sequence and we reply to the client.

The external systems are implemented as mediation modules and stubbed with Java SCA components. I log the message and create a response from these components.

For the scoring service I did a bit more work. I configured a jndi string binding that I can manipulate through the admin console and depending on its value I throw a modeled fault. This is so I can emulate the system being unavailable.

I assume you can complete these tasks without assistance.

You can then run some basic tests and confirm that all your modules are hanging together and everything behaves as it should.

So now we can start thinking about how to approach the case when the scoring service is offline.

The first thing you’re going to need is a new module with a long running process implementing a new ScoringService interface with a one way operation taking the same input parameter type as the actual scoring service mediation.

You can think about this asynchronous LRP as a ‘wrapper’ to the synchronous scoring service.

So, this LRP is called asynchronously (there is no reply) and is instantiated once and only once. You will have to work on your correlation properties/set, so requests are routed to the running instance.

On initial request, an instance is created, the request is placed in a list and an attempt is made to call the scoring service. This call is likely to fail (we wouldn’t be here at all otherwise), so the fault handler executes, which puts the process in receive mode. Every additional request is appended to the list and every time we end up putting the process in receive mode again.

I we haven’t received a request for some time, we timeout the fault handler so we can probe the Scoring Service.

At some point the Scoring Service will be up and running again and for each pending request we will invoke it, get its response, remove the current pending request from the list and invoke the credit card application short running process, letting it know the scoring activity is now complete (we pass in the score result).

Note that ‘resuming’ the credit card application process does not technically resume anything. It simply creates a new instance but with the scoring data already present.

Next you have to modify the short running process so it can detect that the Scoring Service is down, call the async ‘wrapper’ and reply a partial response to the client.

When this short running process is called from the UI and the Scoring Service is up, it behaves exactly as before, and the UI receives a complete response.

When the Scoring Service is down, the fault handler runs, the long running process is called, and the UI receives a partial response.

When this short running process is called by the long running one, the scoring invoke is not attempted, the process proceeds with validating and fulfilling the credit card application, and the reply goes back to the long running process, which you can use for generating customer communications.

This approach keeps the business logic in a single place (the short running process), and effectively deals with offline treatment of requests when a given system is down.

It also addresses resource management, by creating a single long running process, rather than one for each pending request.

And because a long running process state is persisted, all those pending requests survive a server restart, so nothing is ever lost.

ttfn – gabz


WID Heap Status

This is a back to basics tip, but I’m surprised by the number of questions about this from experienced developers.
I like to keep an eye of how much java heap WID is using, particularly while building big workspaces.

So I check ‘Show heap status’ in General Preferences:

Then you’ll see it at the bottom right corner:

WID’s default max heap is 512M. I normally change it to 1024 by editing eclipse.ini and changing -Xms512m to -Xms1024m

Short but sweet

Building a reusable subflow

A lot has been written already about performing common logic to messages using a variety of approaches, but they typically do logging using a message logger or trace primitive. They shy away from using a Service Invoke within a subflow, and for good reason, as the SI primitive’s output terminal returns the response from its invocation and it’s tricky to propagate the original request to the parent flow. Particularly when you don’t know what this original request looks like!

This post focuses on how to model you data and build a reusable subflow to perform message enrichment without knowing the specific message type you’re operating on.

And the reason we are using a subflow, as opposed to a service gateway pattern is because, when a subflow lives in a shared library, it can be selectively reused as if it were a mediation primitive. So we can create a new module, or a new component in an existing assembly, or add it as a primitive to an existing mediation flow. It is a very flexible approach.

The linchpin that enables us to build generic subflows lies in the design and modeling of interfaces and data objects. We would like the subflow to be message type agnostic, we want it to operate within the context of various interactions. In other words, we make no assumptions on the shape and size of the parent flow we might find ourselves within.

But we must have some certainties. Like, if we use the subflow (as in this example) for message enrichment, at some point we will need to navigate to elements in the message body.

In order to guarantee those certainties we will enforce a set of best practices at design time.

  1. Every interface operation has a single input, a single output, and a common set of faults.

  1. Every message type inherits from a base type. This base type contains attributes common to all messages. These are our certainties.

The picture above shows the input parameter type for the retrieveCustomerDetails operation. We create the RetrieveCustomerDetailsRequest business object by inheriting from BaseRequest. The BaseRequest has a attribute that we choose to name ‘header’ of type RequestHeader, which itself inherits from CommonHeader.

Any attribute we model into the CommonHeader BusinessObject is guaranteed to be present in the message. We just need to figure out how to navigate to them (later).

The same is true for faults: create faults that inherit from a BaseFault, add a BaseFault attribute named consistletly (this example uses ‘header’), and make this attribute a superset of CommonHeader. This will ensure your certainties will be also present in faults.

We can start building the subflow now. Create the subflow in a shared library so you can reuse it from any project depending on it.

The purpose of the subflow in this particular example will be to populate a regionId attribute, which is present in all messages (because is a CommonHeader attribute).

We can call this subflow EnrichRegionId. Below is a screen capture of the complete subflow in the mediation flow editor.

At the heart of the subflow there is a Service Invoke primitive, the purpose of which is to retrieve a region code from an external system.

The sublow has an input and three output nodes, the input represents the request message as passed in by the parent flow, the first output will propagate the enriched request message to the parent flow, and the following two output nodes are used for propagating faults.

For those three nodes, their terminal message types are set to anyType.

What this means is that, at development time, the tooling is told that any WSDL type can be fired in or out of these terminals (at runtime this is always true, terminal type information exists for the primary benefit of the tooling).

This is one of the V7 improvements I like the most. I can force V6 into something similar but it is nowhere near as elegant.

Now, lets take a look at what’s going on in the subflow.

I have no idea of which message type I will receive, the service invoke primitive half way down the flow loses my request (its output terminals all relate to its own operation) and I have to find a way to propagate it to the parent flow.

The solution is to keep the /body part of the message in context throughout the flow, using a message element setter.

I used the correlation context out of habit. I don’t have a response flow to worry about here. The context type is xsdAny, so any body type can be safely stored here. One thing to watch out for is developers modeling context data at the parent flow level. This can break things and has to be worked around (by asking developers to include an xsdAny attribute in their context objects, that the subflow can use to store the body), but lets keep it simple.

So that’s my request body stored away. Now we have to operate on /body attributes on a /body type which is mostly unknown.

All we know are the certainties we designed into our data model.

We also know that, for as long as we use the default binding style on our interfaces (document literal wrapped) the SMO path into the body payload will be predictable.

Heres what the SMO representation of an updateCustomerDetails request looks like:

We can get hold of /body, the ‘header’ attribute is our designed in certainty, but we know nothing about what’s between them. All we know is that we are going to find an attribute called ‘header’ two levels down from /body.

The good news is that we can use custom XPath to navigate to it:

In my XML map, the one that provides the Service Invoke with its input parameters, I use a custom XPath transform to retrieve a field from the body in the correlation context:

You can see how if hop over the uncertainties to get to what I need.

After the service invoke, I use a message element setter to enrich the body and propagate it to the parent flow:

1 enriches the message body currently in context and 2 copies it to the body propagated to the parent flow.

Here’s a closer look at 1:

The external system used to retrieve the region id is mediated, so the service invoke uses an internal interface which can return the same faults used throughout the solution. This means I can simply wire those faults to the corresponding output nodes. I’m treating service invoke timeouts and failures as serviceFaults so I can transform and wire those too.

At parent flow level, adding the subflow is very simple. Just drop it in the request flow editor, wire it up and accept the automatic casting proposed by WID (those Set Message Type primitives are automatically generated):

The response flow is inconsequential. Simple wires for message pass-through:

Capturing HTTP Status Code on One-Way Web Service Operations

I am working on a project using WID/WPS/WESB v6.2.0.2 and was asked recently if a mediation flow could capture HTTP response codes from a back-end web service one-way operation.

Naturally my advice was that if an operation describes neither response nor faults, the client is not expected to care about what happens after the request is posted to the service.

Nonetheless, I set about providing a solution, which I would class as a ‘trick’, and hence worthy of a first post in this appropriately named blog.

In summary, the trick consists in calling the web service using an import with HTTP bindings using SOAP/HTTP data serialisation format and basically lying on the import interface. Shameless, but effective.

So, let me show you the trick in more detail.

Lets pretend we have a CustomerService with an addCustomer one-way operation that accepts a Customer as input. Go ahead and create a library named LB_Customer, an interface named CustomerService and a DataObject called Customer.

Then create a module called CustomerService with a Java SCA component just logging the Customer attributes and a web services export. I chose SOAP1.1/HTTP using JAX-RPC. Well, I had no choice. This is the standard in this project.

So, here’s the assembly:

Here’s the CustomerService interface:

And here’s the Customer data type:

Oh, and the very simple Java component code:

You can go ahead, deploy and test. We’re done with the pretence and we can move on to the real trick.

Now create a mediation module, call it MM_CustomerService and do not make the library a dependency. Within this mediation project create your own copy of the Customer data type and the CustomerService interface, but make the addCustomer operation request-response and create a new Response data type.

Here’s the mediation’s private CustomerService interface:

And here’s the Response data type, also private to the mediation:

The private Customer data type is an exact copy of the one in the library used by the target service.

At this point it might be worth showing you my business integration view, so you can check all your bits and pieces are in the right place:

Now comes the hack. You have to make sure the CustomerService interface which is part of the MM_CustomerService mediation project has the same namespace as the one in the library. So go ahead and change it. Go to the interface properties and change the namespace to http://LB_Customer/CustomerService. I told you there was some lying involved.

Now you can assign this interface to your mediation flow component, both as an interface and a reference. Then drop an import into the assembly, wire it to the mediation flow component’s reference and accept the creation of a matching interface on the import.

Right-click on the import and select Generate Binding…-> HTTP Binding. You will have to provide the endpoint URL. You can copy it from the binding tab on the properties for the web services export on the CustomerService assembly.

Here’s a screenshot of the complete assembly:

Go to the properties for the HttpImport, Binding tab, and select SOAP (HTTP) as the default data format. You will need to check the box to show deprecated data formats.

Here’s how you select the data binding:

And here’s the main Binding Properties tab:

Finally go to the Method bindings tab, select the addCustomer bound method and change the HTTP method from GET to POST.

Now let’s implement the mediation flow.

The request flow is a doddle. We simply let the message pass through:

The response flow requires a couple of XML transformations for the out and fail terminals:

The two transformations operate at message root level and map the StatusCode and ReasonPhrase from the smo HTTPHeader to the response body:

You can build, and deploy the two modules now.

Then test the mediation flow component. I’m assuming you’re more than familiar with the integration test client.

What happened?

On this first run I can see in the Events pane that we invoked the http import and that the response fail terminal was fired, routing the response flow to the MapFail xml transform. You can also see the response values. HTTP status code 500

So this is rather good news! Yes, something is not quite right yet but it proves that we are doing what we are supposed to. Capturing HTTP response codes for a service which is, in WSDL/SOAP terms, one-way.

If you have a Console view to hand, you can flounder around for an explanation to this minor frustration, but I’d rather just save you time and show you the relevant log section:

So, it looks like we are missing a SOAPAction header.

I’m still in fits about understanding the purpose of this header. But I understand that there must be a SOAPAction HTTP header for this to work.

So, go back to the properties for the HTTP Import and add an HTTP header named SOAPAction. I used a single white space for its value as there must be a value present.

Now rebuild, republish and retest.

Sweet! We get a 200 OK and we can see in the log the target service doing the sysouts!

And one last thing you may want to do is to stop the CustomerServiceApp (on the Servers view) and retest. You will get the anticipated 404 Not Found:

That’s it, hope you enjoyed this magic trick and feel free to contribute comments and observations, particularly if you get a chance to try something similar on v7.


New Author – Gaby Telerman

Folks, some good news. After recently deciding to mothball this blog, Gaby Telerman has stepped up to the plate and offered to write some new articles on WebSphere Process Server. He doesn’t have a definite posting schedule, but watch this space… more content to come! Thanks, Gaby.

SOA Tips ‘n’ Tricks – Being Mothballed

Folks, I’ve recently taken on a new role working with IBM customers on Dojo (and if that interests you, I’ve launched a great new blog I’m very excited about at, so please go check that out), so there aren’t likely to be any new posts on this blog. However, I’ll leave it in place for some time – hopefully there’s still some useful content on here for those working with WebSphere ESB, Process Server, and the other things I’ve written about over the past few years. Thanks for your attention!

Application Development for IBM WebSphere Process Server and Enterprise Service Bus 7.0

I was recently given a copy of the new book Application Development for IBM WebSphere Process Server 7 and Enterprise Service Bus 7 to review. In general, I’m very impressed. The authors do a good job of explaining general SOA concepts, and the components of the respective IBM products which are used in implementing these concepts, right down to the nitty-gritty of how to implement a sample scenario (with thorough walk-through steps and screenshots). They cover both the key concepts of mediation flows and BPEL-based business processes. The book is light on a few subjects (it doesn’t really discuss the WebSphere Adapters, for example, and the chapter on deployment is a bit light – see the Production Topologies Redbook for more detail), and the hints ‘n’ tips chapter seems messy, but generally, it seems excellent for a beginner trying to learn these products.

(In the interests of disclosure, I received only a free copy of the book for this review).

DynaCache Cache Replication with WebSphere Process Server and ESB

As I blogged about previously, there is a useful technique which involves inserting Java components into SCA modules to cache the results of services using the DynaCache mechanism of WebSphere Application Server. See Gabriel Telerman’s excellent article for more information.

However, if you deploy applications using this technique across a WebSphere cluster, which is fairly typical of a production WebSphere environment, you’ll most likely want to look into WebSphere cache replication (using DRS – the data replication service). This means that rather than having an independent caches on each cluster member (i.e. each server), you’ll have caches that replicate data between each other when it is invalidated or updated in the cache.

This is documented in detail towards the bottom of this InfoCenter page, but broadly speaking you’ll want to modify the properties of the object cache you’re already using. In the article referenced above, the default cache services/cache/distributedmap is used, but to extend this with replication across a cluster, it’s probably appropriate to create your own object cache first if you haven’t already. You then need to specify a “replication domain” for that cache (you’ll need to create one if you don’t already have one), and the replication type. Often “Push only” is suitable for most performance requirements – this pushes new cache entries across the cluster when they are created, modified, or invalidated.

Some other points to be aware of:

  • The Data Replication Service doesn’t always start up straight away on server startup – sometimes it will take a few minutes.
  • It’s primarily intended for internal IBM use, but you may find that the tracing string*=all is useful for figuring out what’s going on inside the cache if it’s not behaving as you expect. It will show cache hits, misses, and replication.

Increasing WebSphere Integration Developer’s Heap Size

Sometimes, when working with WebSphere Integration Developer, you may find that you run out of heap space for its JVM – this will typically result in sudden crashes, and often happens when you have a lot of projects loaded or you’re doing a lot of intensive activity.

In this case, you may want to consider increasing the maximum heap size. Because WebSphere Integration Developer is based on Eclipse, you can do this using the standard Eclipse approach, which is documented on the Eclipse wiki.

Broadly, you’ll want to add some command-line arguments to the WebSphere Integration Developer shortcut. Open the properties of the shortcut from your start menu, and append the following:

-vmargs -Xms512M -Xmx1536M

This will set the initial heap size to 0.5GiB and the maximum heap size to 1.5GiB, for example. You can adjust the value for your needs.


WebSphere Business Process Management v7 Production Topologies Draft Redbook Available

This post is a bit of a personal plug, but I’ve just returned from a Redbook Residency writing the book WebSphere Business Process Management (BPM) V7 Production Topologies Redbook, which illustrates how to set up various BPM products for production, including WebSphere Process Server. It’s a fully updated version of the previous book in the series, which was for V6.2 of the BPM products. The book is now available in draft, so please feel free to take a look – you can send feedback via the feedback e-mail address on that page. I’d also encourage you to rate the book, especially if you think it’s good!