Messages and transformations are key components of the Integration layer. NexJ Studio provides a variety of tools to create messages and transformations for use with external systems.

Adding messages

Add messages to the model in the Integration layer. Multiple message formats are available for use in NexJ Studio.

A message contains a parent or root node that is made up of parts and values. Parts are sub-messages that can contain more parts and values. Values hold primitive data types, such as strings and integers.

You can import XSD/XML schema messages using NexJ Studio's import tool. However, automated addition of other formats may require scripting or third-party software. Alternatively, you can create messages manually.

Message formats

Various message formats are supported and available for use in NexJ Studio:

CSV
Comma separated value. A record is divided into fields, separated by commas, spaces, or tabs.

Fixed
Fixed-length fields ("flat file") format.

JSON
JavaScript Object Notation format for transmitting data objects.

Object
The message is mapped to an internal class.

vCard
A standard for electronic business cards.

XML
XML messages and optional soap wrappers. NexJ Studio allows importing of XSD/XML messages using an XSD importer. For more information, see Importing messages from existing XSD files.

Zip
Zip file archive.

Avro
Avro message format. Commonly used for messaging over the Kafka server.

Importing messages from existing XSD files

NexJ Studio uses an XSD Importer to convert XSD and WSDL files into messages. This tool is built into NexJ Studio and can be accessed from the menu. These message files should already follow the structure that the message is based on.

If there are several files, use the parent XSD and ensure that all related files are in the same directory. All of the XSD files have to be at the location specified, otherwise the child files will not be imported correctly.

To import XSD files in NexJ Studio:

1. Click File → Import.
   The Import dialog opens.
2. Select NexJ Studio → XML Schema/WSDL and click Next.
   The File paths or URLs field opens.
3. Click Browse.
4. The native browse dialog opens.
5. Locate and select the file containing the message you want to convert.
   The native browse dialog closes.
6. Click Next.
   The Message Prefix field opens.
7. In the Message Prefix field, enter a prefix based on the message type.
   For example CDS_ for the CDS type.
8. Select the Create messages for single-referenced root complex type definitions option.
9. Click Finish.
   The Import dialog closes.

The files are converted and message definitions appear in the Model view.

Creating messages

Create messages manually to match the structure of a design.

Use the message editor to implement your design. Within the Overview tab are three main areas. The message hierarchy area on the left side contains the structure of the message. The details area on the top right contains properties of the message. When a mapping is created, the area on the bottom right contains fields that define how the node is mapped to the message.

To create new messages in NexJ Studio:

1. In the Integration layer, click the Messages tab.
2. Right-click inside the Model view and select New Message.
   The New Message dialog opens.
3. In the Name field, enter a meaningful name for your message.
4. Click Finish.
   The new message you created opens in the message window.
5. In the message hierarchy, select the root node.
6. Click the Format field and select the format you want to use for the message.
   For more information on message formats, see Message formats on page 182.
7. Right-click the root node and add desired child nodes as follows:
   • For single primitive datatypes, select Insert Child → Value. In the Name field, enter a relevant name. Select the value type in the Type field. Add any enumerations you want to use.
   • For parts, select Insert Child → Message. In the Ref field, click the Select button and select the reference message you want to use. Click OK.
8. Enter information into the Min Count, Max Count, and Aggregation fields.
   The Min Count and Max Count fields are used to define the minimum and maximum occurrences of the part or value within the message. Aggregation is used to specify whether the child nodes should be read in a specific order.
9. Continue to add child nodes to the root node until you have completed defining the message structure.

Adding transformations

Use transformations to transform one message type to another.

Transformations specify a source and destination message. Components that need to be transformed will be mapped between the source and destination nodes. Both messages must be available to the current model in order to build the transformation.

To add a new transformation to the model:

1. In the Integration layer, click the Transformations tab.
2. Right-click within the Model view and select New Transformation.
   The New Transformation dialog opens.
3. In the Name field, enter a meaningful name for your transformation.
4. Click Finish.
   The new transformation you created opens in the transformation editor.
5. In the Overview tab, set the Source message and the Destination message.

The transformation is added to the model.

Mapping source and destination messages

Transformations require mapping of the source and destination nodes. You can map source parts and values directly to destination nodes or you can modify the source by adding a Script between the connection of the source and destination nodes. You can also add a condition to each mapping in order to filter the output of the source node.

Transforming message collections

If you are mapping messages with collections, levels of nesting within the source and destination messages must be taken into consideration. Mapping values with different nested levels generates unexpected results.

For example, mapping two values (name and age) within one collection to two other values also within one collection creates an expected result: a message is created with those values within the single-level collection. However, attempting to map name and age from two separate collections to the same two values within one collection results in creating two separate messages, each containing one of the two values that were mapped.

A similar result occurs if you are mapping values with different levels of nesting. For example, mapping name and age within one collection to two other values within three levels of nesting results in creating two separate messages of the third level, with each object containing only one of the two values. The collection is implicitly mapped to the first level, and because there is no source collection to match the second level, each value mapped into nodes below the second level gets its own message.

If you want to map the values to a collection of a different level, you must instruct the transformer to treat one of the collections as a non-collection; only one message is constructed in that collection, and all values are mapped to the message. This task is accomplished by adding a dollar sign ($) suffix to the collection name on either the source or the destination fields within the Source and Mapping tabs. The $ suffix cancels the loop on a collection, effectively merging together all items in a collection into one big item.

Creating direct mappings

Source parts and values are mapped directly to destination nodes in the Diagram tab.

After creating a transformation file, follow these steps to map your transformation.

To map a source value to a destination:

1. In the Integration layer, click the Transformations tab.
2. Double-click the transformation you want to map.
   The transformation opens in the transformation editor.
3. In the Diagram tab, find the source and destination nodes that you want to map.
4. Drag the source node onto the destination node.
   A Connector arrow pointing from the source to the destination appears.
5. Continue to map nodes until the message transformation is complete.

You can see a list of mappings in tree format in the Outline view.

Adding scripts

Use a script to modify a source part or value before it reaches its destination. In addition to scripts for individual mappings, the Initializer and Finalizer fields allow you to execute scripts before any mapping is done and after the transformation is complete.

To add a script to a mapping:

1. In the Integration layer, click the Transformations tab.
2. Double-click your transformation.
   The transformation opens in the transformation editor.
3. In the Diagram tab, if the Palette is hidden, click the Show Palette button in the top right of the transformation window to reveal it.
4. In the Palette, click the Script button.
5. Click the Connector arrow that connects the two nodes to add a script. Alternatively, add a script node in an empty space and drag the source and destination nodes onto the script to connect them.
6. Select the script node and click the Property Editor tab.
7. In the Script subtab, enter the script code.
8. In the Mapping subtab, enter information in the Name and Description fields.
9. [Optional] Add a condition in the Condition field, if required.
   A condition is a boolean expression used to filter the output.
10. [Optional] In the Overview tab, enter scripts in the Initializer and Finalizer fields, if required. These scripts will execute before the mapping is done and after the transformation is complete.

Message and transformation testing

Test your messages and transformations to ensure that they function as intended. Use simple Scheme commands within the console or use unit test cases where required.

Scheme commands for testing messages and transformations

Use Scheme commands with sample data in the Minimal Console to test the functionality of your messages and transformations. Place your test code into a scratchpad, available in the Resources layer. Unit Tests are also available to use in the Business Model layer.

Use the following key commands and functions to test your messages and transformations:
(format-message <msg>)
Serializes the message to its raw format. Variants are (format-message-pretty) for a "pretty" appearance and (display (format-message[-pretty])) to skip output of escape characters.

(parse-message body < messages...>)
Unserializes the message from its raw format to an internal message type.

(transform-message <msg transformation-name [args...]>)
Transforms a source message into the destination message using the specified transform.

(debug:message-to-scheme msg [<args...>])
Parses the raw message and generates formatted Scheme code.

Parsing and formatting a CSV message

The following shows an example of the message format for a CSV message:

<Message format="CSV">
   <CSVMapping/>
   <Parts>
      <Message maxCount="0" name="stockInterests">
         <Parts>
            <Value name="ticker" type="string"/>
            <Value name="exchange" type="string"/>
         </Parts>
      </Message>
   </Parts>
</Message>

The following example parses and formats the CSV message:

(define testMsg "ticker,exchange\r\nAAPL,NASDAQ\r\nBBRY,NASDAQ")
(define pMsg (parse-message testMsg "StockInterestCSV"))
(format-message pMsg)