Example payload to UnMarshall

You can copy the XML body into a JSON Converter to make it more readable:
Code Beautify

GLU needs to be told where the parameters are, so you need to read into the XML body for the parameter location.

Examples

First define the parameter name.

In the Unmarshalling section, the attribute name to unmarshal from is specified within the attributes section, with the unmarshalling operation originating from the Body of the SOAP message. Specifically, for the parameter offlineMode, its path within the SOAP message is delineated as follows:

• Parameter Name: offlineMode
• Path: soap:Envelope.soap:Body.ns1:datadictionaryResponse.return

This configuration indicates that the offlineMode parameter is located within the SOAP message’s Body, specifically under the datadictionaryResponse.return node. The attributes section would define additional details related to unmarshalling, such as the attribute’s name within the SOAP message structure.

In the Object / Collection Path field, you would specify the path to access the attribute within the SOAP message. For the offlineMode parameter, this path is:

If you have a payload with classes where you are only interested in the class as a whole with all its underlying attributes, i.e. you have no interest in what those underlying attributes are, you can utilise the ‘Store as Object’ option when unmarshalling your payload. When you select this option, the Attribute Name box will disappear, as you are not dealing with an attribute but with the full object. Instead, you can define a name for your object in the ‘Object / Collection’ path. Here’s an example:

If the object is nested within an array(s) or a class(es), you can set your Object / Collection Path to reference the full path to the object you are interested in. Here are examples:

1. For an array:

2. For a class:

Classes, Objects and Arrays – the basics

Arrays and Objects are two data structures used in API Request and Response messages to organize data:

• Array: Is a collection of similar data items stored in a single variable. Each item in the array has an index number that starts from 0, and you can access each item by its index number. For example, an array of numbers could be [1, 2, 3, 4, 5].
• Object: Is a collection of key-value pairs where each key is a string and each value can be of any data type (numbers, strings, arrays, objects, etc.). You can access the values in an object by their keys. For example, an object could be: { “name”: “John”, “age”: 30, “city”: “New York” }
  

In the context of API Request and Response messages, Arrays and Objects can be used to structure data that is being sent or received, making it easier to access and manage.

An Object and a Class are related concepts in object-oriented programming (OOP), but they are not the same thing.

A Class is a blueprint or a template for creating objects. It defines the properties and methods that the objects created from that class will have. Classes are typically used to model real-world objects, and each object created from the class represents an instance of that class.

An Object, on the other hand, is an instance of a class. It has the properties and methods defined by the class, and can be used to store and manipulate data. An object is created from a class by calling the constructor of the class.

So, to summarize, a Class is a definition of a type of object, while an Object is an instance of that type of object.

Here’s an example in JSON API Response message that represents a list of books:

In this example, Book is a Class that defines a type of object representing a book. It has three properties title, author, and year.

The API Response message is a JSON object that has an array of books, each represented by an object with properties title, author, and year. The code loops through the array of books in the API response and creates instances of the Book class for each book, storing them in the books list. The code then loops through the books list and prints the properties of each Book object.

“Books” in the api_response is an array of objects. Each object in the “books” array represents a book and has properties title, author, and year.

Marshalling (writing) and unmarshalling (reading) are processes used on both the client/sender side (upstream) and the server/receiver side (downstream) of the GLU engine.

Unmarshalling (Reading)

When a request enters the GLU engine, it undergoes unmarshalling—the process of transforming the incoming data into the GLU Object Model (typically in JSON format). This process applies to both inbound requests and outbound responses. Unmarshalling can involve:

• Saving the entire array as-is

• Searching for and extracting specific values

• Storing only part of the array’s contents

Note: For details on how to include arrays in responses, refer to the Response Manager documentation and response template guidelines.

Array Unmarshalling Principles

1. We always use the JSON payload (incoming or response) for our structure when unmarshalling.

2. The array structure in the source must match that of the target parameter (i.e., an array cannot be stored in a single parameter).

3. When unmarshalling with a condition:

• If only one array index matches the condition and both the condition and attribute are on the same level in the JSON structure, then you can save that value into a single parameter.

• Otherwise, the source and target structures must match, meaning the array structure must be preserved.

Unmarshalling Array configuration

Attribute name: This is the name of the specific attribute whose value you want to retrieve from the response or request.

Object / Collection Path: Regardless of the original content type of the request or response, it is always transformed into a JSON structure (you can view this transformation in the DEBUG logs). The Object/Collection Path represents the location of the attribute within this JSON structure. If the attribute is inside an array, this is indicated using [] to show the array elements in the path..

Condition: If you only want to retrieve specific records from a response, you can apply a condition to filter the data. This allows you to extract only the values that meet the specified criteria.

Reading Unmarshalling Logs

Understanding Logs for Value Retrieval

Reading the logs can be very useful for identifying:

1. The value that has been retrieved.

2. The source—where the value is being pulled from.

3. The target—where the value is being saved, including the class or array details.

If you encounter an error such as:

“Error Saving Parameter [value] in GLU OBJECT Due >> must be a class or class from array!”

This indicates that the source and target structures do not match. In most cases, the issue arises because the value should be saved into an array, but is instead being treated as a non-array structure. Ensure that the parameter is correctly saved into an array if needed.

Un-marshalling like for like arrays

If my response from a third party looks like this:

For each parameter in the array, the unmarshalling and parameter properties would be defined as follows:

• Unmarshalling: In this step, the object/collection path is specified to locate the array (e.g., “result”), and the attribute inside each element of the array (e.g., accountID, amount, or balanceType) that needs to be saved into a parameter is identified.

• Properties: In this section, the parameter name is defined, along with the reference to the object (e.g., the “result” array) from which the parameter (e.g., accountID, amount) will be extracted and saved.

Unmarshalling from unnamed arrays

If my response from a third party looked like this:

You can follow the above steps and replace the name of the array with empty square brackets – as shown in the ‘Object / Collection Path’ field below:

Marshalling to unnamed arrays

See example below; the array is nested within an object under the key “array”. This means the array is not at the root level but is a property of an object.

• Inside the “array”, each object only has one property (attribute) with a corresponding value.

If you want to marshal an array and save it as an unnamed array, you can use the ‘Store as Object’ option. This way, the array will be stored as an object (unnamed array). Here’s an example:

To:

Unmarshalling/Marshalling array of values

If the response form third party looks like this:

You can follow the above steps, but leave the attributes fields empty to unmarshall or to marshall.

Unmarshalling using a condition

SCENARIO 1 – Source Array is a FLAT ARRAY OF OBJECTS :

If my response from a third party looked like this:

If you want to retrieve the balance for accountID = 0, you can add a condition to your unmarshalling configuration. This condition will check each record in the array and retrieve the value where the condition is met. Since you expect only one record in the result set to satisfy this condition, you can store the retrieved value in a single parameter.

However, if multiple records meet the condition, you can still store the values in the parameter, but you’ll need to include the object (array) name in the property object field to correctly reference the array in your configuration.

SCENARIO 2 – Source Array is a NESTED ARRAY OF OBJECTS :

If my response from a third party looked like this – you can see that the tx Array is NOT a flat set of objects.

If I want to get the details from the tx array where the it is for the Tariff:

Unmarshalling with a condition where the attribute and condition sit at the SAME level in the array:

Unmarshalling path: The path from the top of the json payload defining the position of where the attribute is sitting: e.g. creditVendResp.transactions.tx[]

Attribute name: accNo

Condition: accDesc==’Tariff Charge‘

Unmarshalling with a condition where the attribute and condition DO NOT sit at the same level in the array:

Unmarshalling path: The path from the top of the json payload defining the position of where the attribute is sitting: e.g. Envelope.Body.creditVendResp.creditVendReceipt.transactions.tx[].amt

Attribute name: value

Condition: tx.accDesc==’Tariff Charge’

This tells us that the unmarshalling path and attribute always go down to the level where the attribute sites. If that level differs to where the condition must be executed, you need to update the condition to understand where in the unmarshalling path to find that condition attribute.

Unmarshalling only part of the array contents

In the above example, if you only want to unmarshal the array and save the accountID and amount fields into an array, then you only need to add those two parameters in the response parameters with the correct configuration included for unmarshalling. This will create the new accounts object without the balanceType parameter.

Consolidating amounts in an array

If I received an array with multiple records for one unique identifier (e.g. accountID) and you wanted to return a consolidated / overall balance for each accountID you could use the following function. This function could be executed on a response handler once the array has been unmarshalled into the engine. It is available in GLU Functions & Formulas

If you receive an array with multiple records for one unique identifier (e.g., accountID) and you want to return a consolidated/overall balance for each accountID, you can use the following function, available in GLU Functions & Formulas:

• parameter 1 (arrayName): the array name where you have unmarshalled your data
• parameter 2 (paramNameConsolidateBy): consolidate to this identifier
• parameter 3 (paramNameToConsolidate): the parameter which you want to add up

This function would work for an incoming array structured like this:

The output would look like this:

1. Set a Derived Parameter:

Start by configuring a derived parameter that will hold the value you intend to compute or override later.

2. Unmarshal Required Parameters:

In the response parameters, unmarshal the necessary values into an accounts array. This will collect all relevant parameters in a structured format, ready for further processing.

3. Use a ‘None’ Handler in the Response Handler:

In your response handler, apply a “none” handler, which effectively prevents any additional transformations. This step allows you to override the derived parameter directly with the function you’ve specified.

4. Override the Derived Parameter:

Finally, use the function in your configuration to set or compute the value of the derived parameter, replacing its initial placeholder.

See the example below:

Unmarshalling a specific position in an array

You can access a specific position in an array by using a shortcut:

In the accounts array, to retrieve the value of the accountID from the first record, you can use the following expression:

• accounts: Refers to the array name.
• [0]: Indicates the position in the array (in this case, the first record).
• accountID: Specifies the value in the first record that you want to retrieve.

Finding a value of a specific position/attribute in an array

If you have unmarshalled successfully into an array – and you want to get one of the values out of the array.

You can create a derived parameter which specifies the detail of what you want to access: ${arrayname[index].attributeName}. This will print the value and make it accessible in the derived parameter.

e.g. ${filtered[0].ti} – this will take the ti value out of the filtered array from index position 0.

When inbound Request Parameters need to be received and stored in the GLU Object Model for later use, you must first configure the ‘Unmarshalling’ process for these specific Parameters.

In the example below:

• the Parameter has a data type of ‘Text’
• the Parameter is passed and received in the ‘Header’
• the ‘Parameter Name’ for the Parameter is ‘USERNAMER’

These configurations define the Type, Location (Header/Body/Query), Parameter Value (Parameter Name), and the Type of the Parameter.

You should configure these settings according to your specific:

• Parameter Type
• Parameter Location
• Parameter Name

Next, the received Parameter must be saved in the GLU Object Model for later re-use, see example below:

• the Parameter type is ‘Text’,
• the Parameter name is translated in this example from ‘USERNAME’ to be saved a ‘userName’,

This defines how the Parameter is stored in GLU and in this example we have translated the Parameter name from ‘USERNAME’ to ‘userName’.

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:

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:

… 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:

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:

Store As Object

For this response:

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