Marshalling is the process of transforming the representation of an object to a data format suitable for storage or transmission. It is typically used when data (parameters) must be moved between different parts of a computer program or from one program to another. The opposite of marshalling is, unmarshalling that is the reverse process, where data is converted from a stored or transmitted format back into an object’s representation.
In the GLU.Engine, all parameters received from external systems must be unmarshalled into a format compatible with the GLU.Engine, known as a GLU object. Later, these parameters can be transformed or utilized for passing on to subsequent receiving systems.
Unmarshalling and Marshalling can be used to change the names or formats of parameters between systems and restructure them into or out of Arrays.
An important convention to note is that when marshalling GLU parameters to be sent to external systems, you reference these variables using the format ${variableName}. If passing the variable into a header, such as the Context Name or URL, the format ${header.variableName} is used. Conversely, when unmarshalling an incoming variable parameter, which doesn’t yet exist in the GLU.Engine, the variable format is simply {} without the dollar sign ($).
Marshalling
This is when a GLU.Engine converts a GLU parameter object into Receiving System object.
In the example below, a Parameter named ‘routeDescription’ is being marshalled to the body of the outgoing request. The template for this request (as defined in the parent Request Manager) is:
Example:
{ “routeDescription” : “${routeDescriptionNewName}” } |
Therefore, ‘routeDescription’ is being marshalled into ‘routeDescriptionNewName’, to be available in the request body.
Note: The addition of the ‘NewName’ to the parameter name was solely for visualisation purposes, in practice it is common to name both the Parameter name and the marshalled one the same. It is also possible to marshal into the Header or the Query.
Header
The Header refers to the ‘Context Name’ of the Request Manager. For example, to route to a variable after the /, you would need to use the .header syntax as follows:
/${header.headerStub}/echo |
… and you would Marshal the ‘headerStub’ attribute to the Header as follows:
Query
The Query refers to the section following the ‘Context Name’ in the Request Manager. For example, to route to a variable after /stub/echo?appId=test , you would need to marshal it to the Query as below.
Exception: If you have a variable in the URL (dynamic URL), you need to marshal the value of the query to the header and insert the ?key in the URL, for example:
/${header.variable}/something?key=${header.queryValueParameter} |
Null Or Empty Parameters
On receiving a null or empty values there are options for what GE should do with these values.
Definition: ’empty’ – is when the parameter exists but there is no value e.g. “value1” : “”
Definition: ‘null’ – is when the parameter does not exist e.g. if expecting to see “value2” in a Response body but “value2” does not exist.
Parameters can be changed from ‘Null’ to ‘Empty’ or ‘Empty’ to ‘Null’ depending on integration requirements.
You also have the option to ‘Ignore’ Null or Empty Parameters. When this is selected, the parameter will not be sent (as empty or null)- IE similar to value4 above. This can be set for all parameters in a payload or per parameter in the Marshalling Control Panel.
Order By
For arrays/lists, this is an expression by which to order the elements before proceeding to marshal the object
Unmarshalling
Multi-Dimensional Arrays
You can also unmarshal multi-dimensional arrays. Multidimensional Arrays can be defined in simple words as array of arrays. For example if you received an XML payload with a multi-dimensional array like this:
<soapenv:Body xmlns="http://schema.gluglobal.co.za/ssc/1.0/DeliveryTrip"> <route xmlns=""> <Zone>CPT</Zone> <ZoneId>910</ZoneId> <PlanReference>0917360</PlanReference> <Personnel> <Driver> <IdNumber>0</IdNumber> <Name>CTH DUMMY DRIVER</Name> </Driver> <CrewMembers> <Crew> <IdNumber>0</IdNumber> <Name>CTH DUMMY CREW 1</Name> </Crew> <Crew> <IdNumber>0</IdNumber> <Name>CTH DUMMY CREW 2</Name> </Crew> </CrewMembers> </Personnel> <RouteId>2200268213</RouteId> <Consignments> <Consignment> <ConsignmentId>999</ConsignmentId> <Dropoffs> <Dropoff> <Type>Delivery</Type> <DropoffId>97625349782634</DropoffId> <DueAt>2019-12-04T09:00:00</DueAt> <SpecialInstructions>N/A</SpecialInstructions> <Dimensions> <Weight>0</Weight> <Pieces>21</Pieces> <Pallets>0</Pallets> <Volume> <Length>0</Length> <Width>0</Width> <Height>0</Height> <Volume>.633213465</Volume> </Volume> </Dimensions> ... etc.
To unmarshall the Volume attribute, in the ‘Volume’ Array, in your Object Collection Path you’d use the following:
Envelope.Body.route.Consignments.Consignment[].Dropoffs.Dropoff.Dimensions.Volume |
Store As Object
For this response:
{ “result”: {“message”: {“prim_email_id”: [“20004: Duplicate email ID, Mobile Number exists”], “prim_id_no”: [“20006: Duplicate ID, ID Number exists.”], “prim_mob_no”: [“20002: Duplicate Mobile / Mobile Number exists”]}, “status”: “E”} } |
Checking ‘Store As Object’ allows for storing of the entire “message” as a single object.
Note: Referencing this “message” requires the following format: [‘message’ without quotes]
{ “result”: { “message”: ${message}, “status”: “${status}” } }
FAQ’s
-
Marshalling is the process of converting the GLU parameter into a format suitable for storage or transmission to a receiving system.
-
Unmarshalling is the opposite of Marshalling, it’s the process of transforming the representation of an object into a format that the GLU.Engine can store and later use.
-
When Marshalling GLU parameters from within the GLU.Engine to be delivered to external systems, the convention is to reference the variables with the format ${variableName} or ${header.variableName} if passing the variable into the header (i.e. the Context Name/URL).
-
When receiving an incoming variable parameter during Unmarshalling in the GLU.Engine, the variable format is simply {} without the $ sign.