Introduction
MuleSoft provides a good structure of documents for developers to learn about its types of variable and properties, but as we all know reading and understanding the concepts is good, but you never beat the act of actually rolling up your sleeves and practicing it in a lab exercise. Learning from experience is what makes the knowledge and concepts stick in the mind. This article is about a step through exercise on how to create/set certain variables and properties in MuleSoft and their scope of existence in the context of a MuleSoft application.
Background
There are some back ground article that helps the reader understand the basic concepts a bit more about what is being discussed. Just click on the hyperlinks below and you will be brought to the MuleSoft documentation about variables and message properties. You will need to have Anypoint Studio installed to conduct this lab exercise.
The Lab Exercise
The sample source code is as per attached at the top of this article. I will walkt through the seetings and codes that have been employed so that you will get an understanding on the mechanics of the code execution.
All Element Available for users to set a variable or property
If you go to the right pane of Anypoint studio, you will see that there is a docked window for "Mule Palette ", if you type the word set into the text box of the mentioned docked window you will see the following selected mule elements.
From top to bottom the the elements are as eloborated below:
Set Payload Element
This element modifies the payload of a mule message, the payload of a mule message is the essential data that is being transported. The following picture shows a red circle which highlights the portion of the mule message that is being modified.
The payload is the data that is passed around to different endpoints for consumption. Mule allow us to set, modify, add and enrich the payload of a message, via the "Set Payload Element"
Set Property Element
The "Set Property Element" allows the user to set outbound properties of a mule message. It is important to understand that all inbound properties of a mule message is immutable, therefore developers are only allowed to set the outbound properties, and outbound property in a source mule flow will become inbound property when it is passed onto another mule flow. If the programmer do not explicitly copy the property from inbound to outbound when passing the message around different flow, the value of the property will eventually be lost in transition. The following diagram shows a red circle highlighting the part of mule message property that is writable. Unlike the payload the inbound and outbound message property is data that describes the payload and not part of the payload that is being passed around different end points. There are there to inform the endpoint on what to expect from the message payload, there are there to describe the payload.
Set Record Variable Element
Record variable are for batch processing flows, discussion about them are beyond the scope of this article. You will be able to read up more about the record variable from the following link.
Set Session Variable Element
This is where it all gets really tricky, session variable are variable that would still maintains its value when it crosses transport, but not all types of session supports transport crossing scopes. In the coming lab experiment the user would learn about the types of session that allows for transport crossing and the types that do not. After setting a session variable programmers are able to access them through the following "Mule Expression Language" (MEL)
#[sessionVars.flow1SessionVariable="Some Value to be passed around transport"]
...
Set Variable Element
"Set Variable Element" implicitly implies that the programmer is trying to set a flow variable during the execution. You can think of a flow variable as akin to a local variable in a function or a method, once the execution flow is out of the function or method the local variable is no longer accessible. After setting a flow variable programmers are able to access them through the following "Mule Expression Language" (MEL)
#[flowVar.flow1SessionVariable="Some Value to be passed around a flow"]
...
Creating Flow 1
The following diagram depicts the complete structure of flow 1:
I will walk through about each component from left to right of the flow, because left to right is the actual programmatic execution at runtime. The following diagram shows the settings of the first component in flow1.
Figure Flow 1 Element 1
There are 3 operations in this "Mule Element", "Set Property" is used to set a new property with name and value, "Remove Property" is used to remove an out bound property of a particular name from the mule message and "Copy Properties" is used to copy an inbound property (with immutable values) to an outbound property that is mutable. "Figure Flow 1 Element 1" shows that I have essentially created a new outbound property called "from" and have set its value to "PostedBYFlow1"
Figure Flow 1 Element 2
There are 2 operations the "Mule Element" depicted in "Figure Flow 1 Element 2", they are namely "Set Variable" is used to set a new flow variable with name and value, "Remove Variable" is used to remove a flow variable of a particular name from the mule message. "Figure Flow 1 Element 2" shows that I have essentially created a new flow variable called "localVariableFlow1" and have set its value to "Flow1 Local Variable "
Figure Flow 1 Element 3
There are 2 operations in this third "Mule Element" depicted in "Figure Flow 1 Element 3", they are "Set Session Variable" is used to set a new session variable with name and value, "Remove Session Variable" is used to remove a session variable of a particular name from the mule message. "Figure Flow 1 Element 3" shows that I have essentially created a new session variable called "flow1SessionVariable" and have set its value to "flow1 Session variable"
Figure Flow 1 Element 4
"Figure Flow 1 Element 4" is depicting a Logger Mule Element. As its name suggest it is used create log data, here we are going to ouput the log data into the Anypoint console. The message text box contains MEL (Mule Expression Language) to display the values set in the previous mule elements. The following code snippet is the value that is keyed in to the Message text box.
#["\n"] Logging from flow1: flow1: #["\n"] inboundProperties.from=#[message.inboundProperties.from] #["\n"] Payload=#[message.payloadAs(java.lang.String)] #["\n"] outboundProperties.from=#[message.outboundProperties.from] #["\n"] flowVars.localVariableFlow1=#[flowVars.localVariableFlow1] #["\n"] sessionVars.flow1SessionVariable=#[sessionVars.flow1SessionVariable] #["\n"]
The snippet of MEL will produce the following sample ouput message in the console.
INFO 2017-02-07 22:37:16,854 [[variabledemo].HTTP_Listener_Configuration.worker.01] org.mule.api.processor.LoggerMessageProcessor:
Logging from flow1: flow1:
inboundProperties.from=PostedBYKian
Payload={"name":"samplePayload"}
outboundProperties.from=PostedBYFlow1
flowVars.localVariableFlow1=Flow1 Local Variable
sessionVars.flow1SessionVariable=flow1 Session variable
Figure Flow 1 Element 5
"Figure Flow 1 Element 5" is depicting a call to a VM endpoint. Choose the request-response radio button so that flow1 will wait for the implementation of the VM endpoint to return control before it continues its program execution, if the programmer selects one-way, "flow1" will not wait for a response from the VM end-point, instead it will proceed with its execution in async mode. In the "Queue Path" text box key in "flow3", this information will be used later when "flow3" is created. Leave all other settings as default.
Flow 1 element number 6 is an exact copy of "Figure Flow 1 Element 4" it is a logging element with the same output as element 4, and same settings, the reason a log element is placed there is to examine what properties and variable is still accessible after a cross VM transport call is returned to "flow1"
Figure Flow 1 Element 7
"Figure Flow 1 Element 7" is depicting a call to a HTTP endpoint. By default these type of end points is request-response by nature, which means that flow1 will wait for the implementation of the HTTP endpoint to return control before it continues its program execution. In the "Path" text box key in "flow2" and select "Method" of "POST", this information will be used later when "flow2" is constructed. Leave all other settings as default.
Flow 1 element number 8 is an exact copy of "Figure Flow 1 Element 4" it is a logging element with the same output as element 4, and same settings, the reason a log element is placed there is to examine what properties and variable is still accessible after a cross through both VM transport and HTTP transport.
Figure Flow 1 Element 9
"Figure Flow 1 Element 9" is depicting a Logger Mule Element. It is the same as "Figure Flow 1 Element 4" the only difference is that it is logging variables and properties of "flow2". The following code snippet is the value that is keyed in to the Message text box.
#["\n"] Logging from flow 1 after control is returned from VM and HTTP endpoint: flow2: #["\n"] inboundProperties.from=#[message.inboundProperties.from] #["\n"] Payload=#[message.payloadAs(java.lang.String)] #["\n"] outboundProperties.from=#[message.outboundProperties.from] #["\n"] flowVars.localVariableFlow2=#[flowVars.localVariableFlow2] #["\n"] sessionVars.flow2SessionVariable=#[sessionVars.flow2SessionVariable] #["\n"]
The snippet of MEL will produce the following sample ouput message in the console.
INFO 2017-02-07 23:18:50,385 [[variabledemo].HTTP_Listener_Configuration.worker.01] org.mule.api.processor.LoggerMessageProcessor:
Logging from flow 1 after control is returned from VM and HTTP endpoint: flow2:
inboundProperties.from=PostedBYFlow2
Payload=<!--?xml version='1.0' encoding='windows-1252'?-->
<name>samplePayload</name>
outboundProperties.from=null
flowVars.localVariableFlow2=null
sessionVars.flow2SessionVariable=null
Flow 1 element number 10 is an exact copy of "Figure Flow 1 Element 5" it is a VM end point element with the same settings as flow 1 element 5, the reason why it is placed after the execution control crosses HTTP transport is so that we can see the behaviour of inbound and outbound properties of a mule message and what will happen to them after they cross multiple different transports.
Creating Flow 2
The following diagram depicts the complete structure of flow 2:
"Flow 2 element number 1" is a HTTP recieving endpoint. quot;Figure Flow 2 Element 1" shows the settings for this mentoned mule element. The path is set to "flow2" (as in flow1 the path will be set to "flow1")
Figure Flow 2 Element 1
Do not set any thing in the "Allowed method" text box so as not to restrict the HTTP recieve endpoint operations.
Figure Flow 2 Element 2
"Flow 2 element number 2" is a outbound property setter it is the same as "Figure Flow 1 Element 1". Except here it is used to set outbound property of "flow2". You can never set or modify the inbound properties of the mule message that is passed to flow2. In this exercise the inbound property "from", so this element is essentially setting a new outbound property for flow2 mule messages called "from"
Figure Flow 2 Element 3
"Flow 2 element number 3" is a flow variable setter it is the same as"Figure Flow 1 Element 2". Except here it is used to set local variable for "flow2". Here the local flow variable is called "localVariableFlow2". You can access it using the same MEL as specified in "Figure Flow 1 Element 2".
Figure Flow 2 Element 4
"Flow 2 element number 4" is a session variable setter it is the same as"Figure Flow 1 Element 3". Except here it is used to set session variable for "flow2". Here the session variable is called "flow2SessionVariable". You can access it using the same MEL as specified in "Figure Flow 1 Element 3".
"Flow 2 element number 5" is a copy of the same logging element in "flow1". It is placed in flow to printout the properties and variables of flow1, so that we would be able to see the fate of the created properties and variables in flow1 once programmatic control crosses HTTP transport to flow2
Figure Flow 2 Element 6
"Flow 2 element number 6" is a Data Weave transformation mule element the highlighted yellow text is the transformation scripts, it is essential transforming the json payload into XML payload, and in case you were wondering, yes all we need is just 3 lines of code to do the transformation.
"Flow 2 element number 7" is a copy of the same logging element in "flow1". It is placed in flow to printout the properties and variables of flow2, this is so that we would be able to see the values of flow2 variables that is being created, and it is also there to test if flow2 session variables crosses transport when control is handed back to flow1
Creating Flow 3
The following diagram depicts the complete structure of flow 3:
"Flow 3" depicts the implementation for the VM enpoint, element number 2 and 3 is a copy of the logging elements created in flow1
Figure Flow 3 Element 1
"Flow 3 element number 1" is an implementation for the outbound VM enpoint being refered in flow1. The path text box must be set to "flow3", this is so that it would be able to process messages sent by flow1.
The run time execution flow
This is the fun part this is the part where MuleSoft shows you how different properties and variables behaves during runtime, it shows you what variables can cross transport and what cant so lets dive in. Follow the enlisted steps test the created mule applicaiton. We are going to use postman to post JSON messages to flow1.
Test Steps
- Start up the mule applicaitno.
- Select the Header tab and key in the highlighted text into postman
Figure Postman Input
- Select the body tab Key in the highlighted text into postman
Figure Postman Input 2
- Click on the send button in postman, then execution is complete observe the returned value, the mule applicaiton has transformed the json payload into XML payload and returned it to postman.
Figure Postman Output
- Collect the logs from Anypoint studio.
Execution Logs Analysis
1. First log of all the new properties and variables created in flow 1
In flow1:
Logging from flow1: flow1:
inboundProperties.from=PostedBYKian
Payload={"name":"samplePayload"}
outboundProperties.from=PostedBYFlow1
flowVars.localVariableFlow1=Flow1 Local Variable
sessionVars.flow1SessionVariable=flow1 Session variable
2. Printing out variables and properties of flow1 and flow2, but notice that flow2 has not been called yet hence the inboud properties that is printed belongs to the same mule message that is passed into flow3 (by flow1), and as described in the previous writings, the outbout property set in flow 1 has now been converted to inbound property for flow3. The intresting thing to note here is that "flow1SessionVariable" has been created in flow1 is not passed together with its mule message to flow3. This is an example of a session variable crossing a VM transport.
In flow3:
Logging from flow 3 : flow1:
inboundProperties.from=PostedBYFlow1
Payload={"name":"samplePayload"}
outboundProperties.from=null
flowVars.localVariableFlow1=null
sessionVars.flow1SessionVariable=flow1 Session variable
Logging from flow 3: flow2:
inboundProperties.from=PostedBYFlow1
Payload={"name":"samplePayload"}
outboundProperties.from=null
flowVars.localVariableFlow2=null
sessionVars.flow2SessionVariable=null
3. Control now has been returned to flow 1 after flow3 has finished it's execution, notince the "from" property is lost because it is not coppied in flow3. The message payload remains the same. Flow1 session and local variable is still has it's value retained after execution control has been returned to it from flow3.
In flow1:
Logging from flow1 after return from Flow 3: flow1:
inboundProperties.from=null
Payload={"name":"samplePayload"}
outboundProperties.from=null
flowVars.localVariableFlow1=Flow1 Local Variable
sessionVars.flow1SessionVariable=flow1 Session variable
4. flow1 now calls the HTTP end point which is implemented as flow2. Notice the from inbound property is no longer avaialbe in flow1 mule message because it was lost in translation from flow3. The other thing to note is that sesion variable set in flow1 cannot cross over to flow2, which means that session variables can only cross certain transports and not all tranports, in this case it cant cross HTTP transport.
In flow2:
Logging from flow 2 : flow1:
inboundProperties.from=null
Payload={"name":"samplePayload"}
outboundProperties.from=PostedBYFlow2
flowVars.localVariableFlow1=null
sessionVars.flow1SessionVariable=null
Logging from flow 2: flow2:
inboundProperties.from=null
Payload=<?xml version='1.0' encoding='windows-1252'?> <name>samplePayload</name>
outboundProperties.from=PostedBYFlow2
flowVars.localVariableFlow2=Flow2 Local Variable
sessionVars.flow2SessionVariable=flow2 Session variable
5. Runtime execution control flow has now been returned back to flow1 after flow2 finishes its run. Flow2 outbound properties has not become an inbound property when it reaches flow1. Flow1 session and local variables is still accessible, but flow2 session variable is not able to cross transport to get to flow1.
In flow1:
Logging from flow1 after control return from VM and HTTP end points: flow1:
inboundProperties.from=PostedBYFlow2
Payload=<?xml version='1.0' encoding='windows-1252'?> <name>samplePayload</name>
outboundProperties.from=null
flowVars.localVariableFlow1=Flow1 Local Variable
sessionVars.flow1SessionVariable=flow1 Session variable
Logging from flow 1 after control is returned from VM and HTTP endpoint: flow2:
inboundProperties.from=PostedBYFlow2
Payload=<?xml version='1.0' encoding='windows-1252'?> <name>samplePayload</name>
outboundProperties.from=null
flowVars.localVariableFlow2=null
sessionVars.flow2SessionVariable=null
6. Finally the last step in flow1 is to call flow3 again to see the session variables of flow1 and flow2, only session variables from flow1 is passed to flow3..
In flow3:
Logging from flow 3 : flow1:
inboundProperties.from=null
Payload=<?xml version='1.0' encoding='windows-1252'?> <name>samplePayload</name>
outboundProperties.from=null
flowVars.localVariableFlow1=null
sessionVars.flow1SessionVariable=flow1 Session variable
Logging from flow 3: flow2:
inboundProperties.from=null
Payload=<?xml version='1.0' encoding='windows-1252'?> <name>samplePayload</name>
outboundProperties.from=null
flowVars.localVariableFlow2=null
sessionVars.flow2SessionVariable=null
Conclusion
From this lab experiment we can make the following bullet point conclusion.
- Session Variables - Crosses only certain transport but not all transports, in this lab exercise we have provend that session variables is capable of crossing over VM transport but not HTTP transport.
- Flow Variables - are local variabls akin to variables created in functions and methods, once execution goes outside of the scope it is no longer accesible.
- Outbound Properties- are able to cross transport but programmers must remember to copy them over from inbound to outbound property if they whis to retain the property value cross different transport.
