Working with messages

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:

1. In the Integration layer, select the Messages tab.
2. Right-click the list area inside the tab and select New Message. The New Message dialog opens.
3. Name the message training:PersonXML.

4. Click Finish. The new message opens in an editor window.

5. Do one of the following:

   1. 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

   2. Define the message using the Overview tab:
      1. Select the training:PersonXML root node.
      2. Set the format to XML.
      3. Right-click the training:PersonXML root node, select Insert Child > Value and specify the following details:
         1. Name: firstName
         2. Type: string

      4. Add another child value and specify the following details:
         

         1. Name: firstName
         2. Type: string

         3. Min Count: 1

      5. Right-click the training:PersonXML root node and select Insert Child > Message and specify the following details:

         1. Name: address
         2. Min Count: 1
      6. Right-click the address node and select Insert Child > Value and specify the following details:
         1. Name: street
         2. Type: string

      7. Add another child value and specify the following details:
         

         1. Name: city
         2. Type: string

         3. Min Count: 1

6. 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:

1. Use an existing scratchpad or create a new one.

2. 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))

3. Save the scratchpad.

   

   To avoid errors and warnings in the scratchpad, select the XML text, right-click and select Toggle Comment.

4. Run the Server Console.

5. In the Console, execute each statement from the scratchpad individually and review the results.

6. Copy the XML output from the last statement ("pretty wire format") to the bottom of the scratchpad for comparison later on.

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

1. Use an existing scratchpad or create a new one.

2. 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)

3. Save the scratchpad.

4. 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:

1. In the Integration layer, select the Messages tab and open the training:PersonXML message.

2. In the training:PersonXML message, select the firstName node and click Create Mapping.

3. In the XML Mapping section, change the Type from element to attribute.

4. Select the lastName node and click Create Mapping.

5. Change the Type from element to attribute.

6. Select the address node and click Create Mapping.

7. Set the Node to location.

8. 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:

1. Open the scratchpad you used earlier in this learning module.
2. 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.
3. 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:

1. Open your scratchpad.

2. In the Console, execute the first two statements from the scratchpad.
   You should see errors generated because of the changes you made to the training:PersonXML message.

3. 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 of training: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>"
     )

4. At the bottom of the scratchpad, add the following statement.

   CODE

   ((msg'location)'city)

5. In the Console, execute each of the statements from the scratchpad.

6. 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:

1. Create a new message called training:PersonXMLCollection.
2. In the editor window, click the Overview tab and set the Format to XML.
3. Add a child message to the training:PersonXMLCollection root node and specify the following details:
   • Name: persons
   • Max Count: 0

   • Ref: training:PersonXML

4. Save the message.
   The training: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

1. 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))

2. In the Server Console, execute each of the statements from the scratchpad individually and review the results.
   Because there is no address for the robin message, you should see errors generated.
3. In the scratchpad, add an address to the robin message. Use the same address structure as in the batman message.
4. Save the scratchpad.
5. In the Console, execute each of the statements from the scratchpad again and inspect the results.
6. When you are finished, stop the Console.