Over a million developers have joined DZone.
{{announcement.body}}
{{announcement.title}}

Implementing Message Enrichment in MuleSoft

DZone's Guide to

Implementing Message Enrichment in MuleSoft

Message Enrichment is a common use case for integration software. This tutorial will teach you how to use it in MuleSoft.

· Integration Zone
Free Resource

Share, secure, distribute, control, and monetize your APIs with the platform built with performance, time-to-value, and growth in mind. Free 90 day trial 3Scale by Red Hat

1.0: Overview

Message Enrichment is a common use case for Integration Software. A scenario for message enrichment is depicted in Figure 1.0.

Figure 1.0

There is an incoming payload that must be enriched with certain data before the integration system can pass it further down the processing chain to an outbound endpoint. The message enricher pattern is depicted states that the original inbound payload is to be retained, but the enriched message is attached as an additional payload before being relayed to an outbound endpoint. MuleSoft offers this support via the message enricher scope. That is all fine, but what if we want to modify the original payload. The following sections are lab sessions showing the users how this can be done.

2.0: Hypothetical Scenario

Let's say you are an integration developer and have been challenged to build an integration scenario depicted in Figure 2.0.
Figure 2.0

In Figure 2.0, you have to build an integration module that accepts an inbound payload (1), you will need to fire a call to an external web API (2) to get additional data, so that you could enrich the original inbound payload with the acquired data (3), and further pass it on down to an outbound endpoint (4).

Let's put some meat into this hypothetical scenario; let's say the expected inbound payload is a list of international orders in JSON format like the following (1):

2.1: Inbound Payload

{ 

"order":[
{
   "country" : "New Zealand",
   "item" :{
      "currency":"$",
      "name":"Shovel",
      "qty":"2",
      "unitPrice" : "10"
   }
},
{
   "country" : "Malaysia",
   "item" :{
      "currency":"$",
      "name":"Satay",
      "qty":"2",
      "unitPrice" : "10"
   }
}
]
}

2.2: Additional Enrichment Data

When the message enrichment processor makes a call to the external web API (2), the data returned by this external web API is as per the following:

{
"Currency": [
{"Country":"New Zealand","CurrencyCode":"NZD", "CurrencyDesc":"New Zealand Dollars"},
{"Country":"Malaysia", "CurrencyCode":"MYR", "CurrencyDesc":"Malaysia Ringgit"},
{"Country":"Singapore", "CurrencyCode":"SGD", "CurrencyDesc":"Singapore Dollars"},
]
}

2.3: Outbound Payload

The Mule message enricher must take this additional data and select the correct currency code for all the orders located in the inbound payload (3), and as a result of the enrichment operation, the payload would be modified to the following:

{
  "order": [
    {
      "country": "New Zealand",
      "item": {
        "currency": "NZD",
        "name": "Shovel",
        "qty": "2",
        "unitPrice": "10"
      }
    },
    {
      "country": "Malaysia",
      "item": {
        "currency": "MYR",
        "name": "Satay",
        "qty": "2",
        "unitPrice": "10"
      }
    }
  ]
}

The orders in the inbound payload with the "currency" value of "$" is replaced with its respective country's currency code. As described earlier this is a hypothetical scenario but I believe that this scenario will always occur in either one incarnation or another. Section 3.0 will show how this can be done via MuleSoft, so let’s dive in.

3.0: Lab Session

The following picture shows the end result of building a Mule flow that is capable of processing inbound payload as described in Section 2.0:

Figure 3.0

The Mule flow is numbered with execution step sequence so that it would be easier for me to walk readers through the processing mechanics of it all.

The Git repository with the full source code can be found here

In Figure 3.0, you will be able to see two flows, the main flow is called "messageenrichersFlow" this flow is an implementation of the "Message enricher" pattern. The second flow "ExternalWebAPI" flow is used to simulate a call to an external system and returning a payload of additional data to be populated to the original inbound data.

At (1) and inbound JSON payload (as described in 2.1) is received by "messageenrichersFlow", at (2) we need to convert the JSON payload to a Java object so that it could be easily manipulated via the "Mule Expression Language" (or MEL). (3) is an implementation of the first message enricher scope with the name of "Msg Enricher: Getting List Of Currency", here I have simulated a call to an external system via a VM endpoint, when this called is relayed to (3.1.1), it will reply back to the main flow with a hardcoded payload at (3.1.2) (the content of the hardcoded payload is as per described in section 2.2).

The currency list returned (section 2.2) is in JSON format; I need to convert it into a Java object so that I can programmatically access it for further processing. We cannot use the "JSON to Object" transformer here as its implicit usage is to transform a message payload; the additional currency list returned from the (3.1.1) is not in the message context of "messageenrichersFlow". The JSON message that is returned is stored in a flow variable "currencyCode" as depicted in Figure 3.1 below.

Figure 3.1

In order to convert the content of flow variable "currencyCode" into a Java collection object, we have to create another message enricher (4). In this new message enricher, we will use the expression transformer to transform the JSON string to a Java HashMap. The following is the code snippet that is being used in the Expression transformer:

new com.fasterxml.jackson.databind.ObjectMapper().readValue(flowVars.currencyCode, java.util.HashMap)

I made use of the Jackson Data bind api to convert the JSON data (in section 2.2) to a Java Hashmap, as a result of executing the Java code the JSON data will be converted to the following Java Object depicted in Figure 3.2 below:

Figure 3.2

This new Java object is then stored in a flow variable called "JavaCurrencyCode."

In number (5), I made use of the "For Each" scope to loop through the inbound payload order by order. I have made use of the Groovy script component (5.1) to implement an inner loop to traverse through the Currency List Java Hashmap; this is so that I could select the correct currency code for the order being inspected, we can’t use the Mule's "For Each" scope as an implementation for the inner loop because it is not capable of executing the break mechanism. I want to be able to break the inner loop when the matching country is found; Groovy scripting is the only option for me (you could also user other script language, e.g. Ruby). The following is the Groovy script used:

def curArrayList = flowVars.JavaCurrencyCode.get("Currency");
for (i = 0; i <curArrayList.size(); i++) {
    def item = curArrayList.get(i);
    System.out.println(item.get("Country"));
    if(payload.country.equals(item.get("Country"))){
      payload.item.currency = item.get("CurrencyCode")
      break;
    }
}

Notice that, in the Groovy script, you can reference Mule objects directly- for instance, line number 5 and 6, you would usually access the payload object via MEL by enclosing it in the following format #[...]. In Groovy script, you are able to access it directly. How cool is that?

After number (5), the payload is then transformed back to JSON format so that it could be passed on to the other endpoints. The following postman screencap shows the inbound JSON data that is being passed in to the Mule application and the resulting outbound JSON that is retuned with all its currency code being modified.

Image title

4.0: Conclusion

While building the integration module for the mentioned hypothetical scenario, I have made a few observations I would like to share. Please feel free to give me some feedback and comments pertaining to the observations that I have made.

  • Message Enricher Scope - We can only have one operation in a message enricher scope; we can't nest additional message processor in a Message enricher scope. For this reason, I have created two separate message enricher scopes (Figure 3.0 (3) & (4)).
  • For Each Scope - Mule's For Each scope is better used for making complete iterations through a collection; it does not have the capability of doing incomplete iteration because it is not capable of executing the break mechanism. To cater for break mechanism in loops, it is best to use scripting components.
  • JSON String Processing - To quote MuleSoft documentation, "There is no standard language currently for querying JSON data graphs in the same way XPATH can query XML documents. Mule provides a simple query syntax for working with JSON data in Java, called JsonPath." Depending on the size of the JSON payload, if the size is inconsequential, then it would be easier for programmatic manipulation if we convert the JSON payload into Java Object. (as shown in Figure 3.0 (4.1))

Discover how you can achielve enterpriese agility with microservices and API management

Topics:
message enricher ,groovy ,mulesoft

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}