Working with messages
Learning objectives
This lesson introduces you to messages. You will create an XML message, write scripts to format and parse the message, and explore how adding an XML mapping to the message affects the formatting and parsing. On completion, you will have learned:
About messages.
About the different types of message formats.
The structure of a message.
- How to add mappings to a message.
How to create an XML message in script.
How to format and parse message inputs in script.
Key concepts
Different systems communicate by sending and receiving messages via channels. A message carries a unit of information from a source system to a destination system. For each message, you specify a format that defines how the message is represented externally during transport. In NexJ Studio, messages are part of the Integration layer.
Message formats supported include:
- CSV -List of comma-separated values.
- JSON -JavaScript Object Notation messages.
- vCard -A vCard file, a standard format for electronic business cards.
- XML - An XML mapping. SOAP (Simple Object Access Protocol) messages are also supported by this format.
- ZIP - A compressed ZIP archive file.
- Object - An object mapped to an internal class.
- Avro - A mapping to an Avro message type
Each message contains a root that contains parts and values.
- Part - A type of sub-message that shares its parent's format. Similar to the parent message, the format affects the way in which parts are mapped to their external representation.
- Value - Holds primitive data types, such as strings and integers. Both the parent message, or root, and its parts can contain values.
Creating a message
In this lesson, you will create a new message called training:PersonXML
containing the following information:
- First name
- Last name (required)
- Address, consisting of:
- Street
- City (required)
When you are done, the message should look like the following:
Learning activity
To create a message file:
- In the Integration layer, select the Messages tab.
- Right-click the list area inside the tab and select New Message. The New Message dialog opens.
- Name the message
training:PersonXML
. Click Finish. The new message opens in an editor window.
Do one of the following:
Enter the following XML code or drag and drop it on the Source tab.
XML<Message format="XML"> <Parts> <Value name="firstName" type="string"/> <Value minCount="1" name="lastName" type="string"/> <Message minCount="1" name="address"> <Parts> <Value name="street" type="string"/> <Value minCount="1" name="city" type="string"/> </Parts> </Message> </Parts> </Message>
or
- Define the message using the Overview tab:
- Select the
training:PersonXML
root node. - Set the format to XML.
- Right-click the
training:PersonXML
root node, select Insert Child > Value and specify the following details:- Name:
firstName
- Type:
string
- Name:
Add another child value and specify the following details:
- Name:
firstName
- Type:
string
Min Count:
1
- Name:
Right-click the
training:PersonXML
root node and select Insert Child > Message and specify the following details:- Name:
address
- Min Count:
1
- Name:
- Right-click the address node and select Insert Child > Value and specify the following details:
- Name:
street
- Type:
string
- Name:
Add another child value and specify the following details:
- Name:
city
- Type:
string
Min Count:
1
- Name:
- Select the
- Save your work.
Formatting a message input to XML
In this learning activity, you will use a scratchpad and Scheme script to create an unformatted message and convert it into XML format for display. The first statement of the script creates the message and specifies values for all the fields. The four statements that follow display the message in a variety of XML formats.
Learning activity
To create and format a message:
- Use an existing scratchpad or create a new one.
Enter the following code in your scratchpad.
SCHEME(define msg (message (: :class "training:PersonXML") (: firstName "Kate") (: lastName "Magenta") (: address (message (: street "Broadway Ave") (: city "Manhattan") ) ) ) ) ; See the "wire format" (the XML string) (format-message msg) ; See the "wire format" without the escape characters (display (format-message msg)) ; See the "pretty wire format" (format-message-pretty msg) ; See the "pretty wire format" without the escape characters (display (format-message-pretty msg))
Save the scratchpad.
To avoid errors and warnings in the scratchpad, select the XML text, right-click and select Toggle Comment.
Run the Server Console.
In the Console, execute each statement from the scratchpad individually and review the results.
Copy the XML output from the last statement ("pretty wire format") to the bottom of the scratchpad for comparison later on.
Save the scratchpad.
Parsing an XML input to a message
In this learning activity, you will use a scratchpad and Scheme script to create an XML string and parse it into a defined message format.
The first statement in the script defines a string containing a number of XML fields and values. The second statement attempts to parse the XML string into the specified message format. The three statements that follow, display values from the parsed message.
Learning activity
To create an XML message and parse it:
- Use an existing scratchpad or create a new one.
Enter the following code in the scratchpad.
SCHEME; Define an XML string (define body "<TrnPersonXML> <firstName>Angela</firstName> <lastName>Rajatma</lastName> <address> <street>Jana Alata Road</street> <city>Mumbai</city> </address> </TrnPersonXML>" ) ; Parse the external format to the internal representation (define msg (parse-message body "training:PersonXML")) ; Inspect elements of the message (msg'firstName) (msg'address) ((msg'address)'city)
Save the scratchpad.
Use the Server Console to execute each of the statements from the scratchpad individually and inspect the results.
Adding mappings to a message
A mapping is used to control how message elements are mapped between internal and external format. Mappings are used to modify how a message is formatted into an external format, and how externally formatted information is parsed into a message.
In this learning activity, the first name and last name nodes are mapped to XML attributes, while the address node is mapped to a node (XML element) called location.
Learning activity
To define a mapping for the training:PersonXML
message:
In the Integration layer, select the Messages tab and open the
training:PersonXML
message.In the
training:PersonXML
message, select thefirstName
node and click Create Mapping.- In the XML Mapping section, change the Type from
element
toattribute
. Select the
lastName
node and click Create Mapping.Change the Type from
element
toattribute
.Select the
address
node and click Create Mapping.Set the Node to
location
.Save the changes made to the message.
Reviewing how mapping impacts formatting
Run the Scheme script from your scratchpad again to see how mappings affect the output.
Learning activity
To see the effect of your mapping:
- Open the scratchpad you used earlier in this learning module.
- In the Console view, stop the Server Console by clicking the Terminate button , then restart it by clicking the Run Scheme Console button in the toolbar.
- In the Console, execute each statement from the scratchpad and compare it with the output from the previous exercise.
Observe that firstName
and lastName
are now attributes of training:PersonXML
rather than elements, and the address element is now the location element.
Reviewing how mapping impacts parsing
Run the script from your scratchpad to see how mappings affect the output.
Learning activity
To see the effect of mapping on parsing:
Open your scratchpad.
In the Console, execute the first two statements from the scratchpad.
You should see errors generated because of the changes you made to thetraining:PersonXML
message.In the scratchpad, modify the
(define body)
statement with the following changes so that it parses correctly:Remove the
<firstName>
and<lastName>
elements and add them as attributes oftraining:PersonXML
.Change the
<address>
element to a<location>
element.
The updated define statement should be similar to the following.CODE(define body "<training:PersonXML firstName=\"Angela\" lastName=\"Rajatma\"> <location> <street>Jana Alata Road</street> <city>Mumbai</city> </location> </TrnPersonXML>" )
At the bottom of the scratchpad, add the following statement.
CODE((msg'location)'city)
In the Console, execute each of the statements from the scratchpad.
When you are finished, save the changes made to the scratchpad.
Creating an XML message containing a collection of messages
In this learning activity, you will create a new message called training:PersonXMLCollection
that stores a collection of people. The list should reference training:PersonXML
so that each element of the list is its own training:PersonXML
message.
Learning activity
To create a message that contains a collection:
- Create a new message called
training:PersonXMLCollection
. - In the editor window, click the Overview tab and set the Format to XML.
- Add a child message to the
training:PersonXMLCollection
root node and specify the following details:- Name:
persons
- Max Count:
0
Ref:
training:PersonXML
- Name:
- Save the message.
Thetraining:PersonXMLCollection
message should look similar to the following:
Formatting a message collection to XML
In this learning activity, you will use a scratchpad and Scheme script to create two unformatted messages, combine them into a message collection, and convert the collection into a specified format for display.
The first two statements in the script create the messages and specify values for various fields. The next statement collects the messages into a message collection. The final statement displays the collection in the format defined by its class.
Learning activity
In your scratchpad (use an existing scratchpad or create a new one), enter the following code:
SCHEME; Create some persons (define batman (message (: :class "training:PersonXML") (: firstName "Bruce") (: lastName "Wayne") (: address (message (: street "1007 Mountain Dr") (: city "Gotham City") ) ) ) ) (define robin (message (: :class "training:PersonXML") (: firstName "Dick") (: lastName "Grayson") ) ) ; Create the collection of the persons (define msg (message (: :class "training:PersonXMLCollection") (: persons (collection batman robin) ) ) ) ; See the "wire format" (display (format-message-pretty msg))
- In the Server Console, execute each of the statements from the scratchpad individually and review the results.
Because there is no address for therobin
message, you should see errors generated. - In the scratchpad, add an address to the robin message. Use the same address structure as in the
batman
message. - Save the scratchpad.
- In the Console, execute each of the statements from the scratchpad again and inspect the results.
- When you are finished, stop the Console.