Previous – Message Translator | Index | Next – Content Enricher
This week we'll study a Message Transformation pattern known as Envelope Wrapper.
When do I use this pattern?
Envelope Wrapper is used when the message payload (header + body) is wrapped inside a payload for sending the payload through network. SOAP Envelope is an example of Envelope Wrapper pattern.
Wrapping a letter (a paper one ;)) in an envelope is analogous to the Envelope Wrapper pattern. The Envelope serves two purposes, it hides the actual letter but keeps the routing information like the address visible. Similarly, the envelope in integration may encrypt the message payload while keeping the routing information in the format usable for routing systems.
Envelope Wrapper in CPI
In CPI, let's explore the SOAP Receiver Adapter to see how message is enveloped.
Integration Flow
Envelope Wrapper - Converting Temperature
This simple integration flow uses sample temperature conversion service by W3 Schools. The integration flow starts immediately using Timer Start, sets the input using Content Modifier, invokes the Temperature Conversion service using Command Message pattern, and finally logs the output.
Envelope Wrapper in Action
While writing this blog, I found this cool place to see how Adapter transforms the message. These are the steps I followed to find this hidden trace.
Step 1 - Turn on Trace
The Envelope Wrapper is one abstraction layer below the payload. We can use Trace Log Level to understand how Envelope Wrapper pattern is used inside SOAP Receiver Adapter.
Turn on the Trace with these steps
- Navigate to Monitor
- Search for the Integration Flow Name
- Change Log Level to Trace
- Navigate to Monitor Message Processing
Turn on Trace
Step 2 - Deploy the Flow
Now that the Trace is on, let's deploy the flow. As Timer Start is used with the setting on Run Once, the flow will execute immediately upon deployment.
Step 3 - Find the Traced Message
Some of us may have multiple nodes. If you have multiple nodes, you'll have multiple messages. Whether you have multiple nodes or a single node, follow these steps to find the traced message:
- Click on the message
- Click on Logs
- Check if Log Level is Trace with a hyperlink, if not do steps 1 to 3 on next message in the list.
Find the Traced Message
Step 4 - Request Message without Envelope
Now, we are looking at the trace of the message. Let's follow these steps to see the message as we set in the Content Modifier. This is the Request Message without Envelope.
- Click on SOAP
- Click on Message Content
- Click on Payload
Request Message without Envelope
Step 5 - Request Message with Envelope
Let's click on > arrow in top-right corner to check next step as shown in screenshot below.
Step 5a
Now, we can see that the envelope is added to the message payload. In the screenshot below, we can see that the selected part is same as above screenshot, whereas SOAP envelope is added around the payload.
Request Message with Envelope
Step 6 - Response Message with Envelope
Let's click on > in top-right corner once again to check Response Message with Envelope.
Step 6a
Here's how the response message looks with envelope:
Response Message with Envelope
Step 7 - Response Message without Envelope
The SOAP Receiver Adapter removes the envelope so that only message can be processed without worrying about the details of the SOAP Envelope.
Click on Log to see Response Message without Envelope:
Response Message without Envelope
Conclusion
Envelope Wrapper is used when the protocol or the end system require message to be in encrypted format but the routing information needs to be elevated outside the message. SOAP is a good example of Envelope Wrapper pattern and CPI has in-built adapter for handinng the Envelope.
References/Further Readings
- Envelope Wrapper Pattern in Enterprise Integration Patterns
- Temperature conversion service by W3 Schools
- EIPinCPI
- CPI Components
Hope this helps,
Bala
Previous – Message Translator | Index | Next – Content Enricher
- SAP Managed Tags:
