Reading Time: 8 minutes

One  of the enterprise integration patterns that Mule hasn’t explicitly supported up until now is the “Content Enricher”.  Enrichment has of course been possible but it hasn’t been as easy as it should have been.  That’s changing for Mule 3.1 as we introduce support for message enrichment.  Read on to learn what you can do with the new enricher and see some examples..

When do I need a content enricher?

First let’s remind ourselves why you might want to use  a content enricher:

latest report
Learn why we are the Leaders in API management and iPaaS
Read reports

In a message processing system other than moving messages around and transforming them, it is a common requirement to actually need to enrich the message with information (data) that isn’t provided by the source system.  A simple example of this is when the message from the source system contains a ZIP code but the target system needs the two letter state. In this case a message enricher can be used to lookup state using the ZIP code from an enrichment resource.   The enricher calls out to the enrichment resource with the current message (containing the zip code) then enriches the current message with the result.

Using a Content Enricher in Mule

So now lets take a look out how you would implement the simple use case for an enricher described above:

<flow name="orderProcessingFlow">
   <inbound-endpoint ref="orderEndpoint"/>
   <enricher target="#[variable:address]">
       <outbound-endpoint ref="stateLookup"/>
   </enricher>
   <outbound-endpoint ref="orderStep2"/>
</flow>

This is a very simple flow with one-way inbound and outbound endpoints that acts as part of an order processing pipeline.  This flow uses an enricher to add a state variable to the current message with the state that the addressLookup endpoint returns.  The ‘target’ attribute defines how the current message is enriched using a MessageEnricher which uses the same syntax as expression evaluators.  Currently only a ‘header’ and ‘variable’ enrichers are supported but we’ll be adding other expression enrichers in the future.

A ‘variable’ is available for the lifetime of the flow and is accessible using the ‘variable’ expression evaluator e.g. #[variable:foo]

In this particular example the addressLookup endpoint receives the full message, in some cases this might be a generic service that doesn’t know how to parse our order message but rather just a ZIP string.  It is very easy to improve the configuration to support this, consider the following snippet.

<flow name="orderProcessingFlow">
   <inbound-endpoint ref="orderEndpoint"/>
   <enricher target="#[variable:address]">
       <outbound-endpoint ref="stateLookup">
           <expression-transformer evaluator="xpath" expression="/order/address/zip" />
       </outbound-endpoint>
   </enricher>
   <outbound-endpoint ref="orderStep2"/>
</flow>

Note: The “enrichment resource” configured inside the <enricher> element can be any message processor, outbound endpoint, processor-chain or flow-ref.  If using an outbound-endpoint then of course it should use the request-response exchange pattern.

Example

The <enricher> element also allows you to extract a value from the message returned by the enrichment resource.  This is important when the the external service returns more than the specific value that we need.  Let me give an example:

Building on the above example, you now have a requirement to validate the credit card used for the order as well as add the full address using the ZIP code.  The credit card validation process should populate a variable called “paymentValidated” with the validation response code, this will be used later on.  We can easily perform credit card validation by calling out to an authorization service like Authorize.Net to perform this validation, but we have a problem this cloud connector returns more than just the response code.

The solution is to use the enrichers ‘source‘ attribute which will select a value from the result message before using it to enrich the target.

This approach allows you to map content in the response message from the enrichment resource to new variables or headers on the current message.

More Advanced Usage

If you have a more advanced use case you can also map multiple values in the enrichment resource response to multiple new variables/headers on the current message, this is done using child <enrich> elements each of which has source and target attributes.

Note: if you use child <enrich> elements the source/target attributes on the top level <enircher> are not allowed.

Hopefully using the new content enricher enriches your experience with Mule!   If you haven’t already downloaded and tried Mule 3.1 then do so and as always please provide feedback you might have on the this new feature as well as on anything else.

Also if you are interested in cloud connectors for payment services as shown in the last example here be sure to check out the Mule Payment Services blog post.