Graphically modeling a JSON array in a message map

In the Graphical Data Mapping editor, you can use the Add User-Defined function to create a JSON array in a JSON message. You can create JSON arrays where all occurrences of the array are of the same type.

Before you begin

Create a message map with the output domain set to JSON. For more information, see Graphically modeling a JSON message in a message map

About this task

To create a JSON array in a JSON message by using the Add User-Defined function, you must set the type of the user-defined element to JSONArray_Default and then set the type of the Item element to the required type.

When you define multiple arrays in your map, each JSON array has a type JSONArray_N, where N describes the unique id of the array in the map.

Shows multiple JSON arrays in a map, each one with a different type

You can reuse the definition of a JSON array in your message map. For more information, see Reusing a JSON message, a JSON object, or a JSON array in a message map.

Procedure

Complete the following steps to create a JSON array in a JSON message:

  1. Right-click any, and select Add User-Defined.

    Shows the option Add User-Defined

    The element element1 is created under the any element.

  2. Click element1 and enter the name of the JSON array.

    By default, the user-defined element is created as a string element.

  3. For element1, click string, and select JSONArray_Default as its type.

    The repeating element Item is created automatically. Item is used internally by IBM® App Connect Enterprise. You cannot change this name. Item will not appear in your JSON data. Item is the logical tree representation of each instance in the JSON array. For more information, see JSON parser and domain.

    You cannot change the cardinality of Item. For more information, see Configuring the cardinality of a user-defined element.

    Shows the element Item
    Note: Item is the name of the repeating element that describes the JSON array. All the values in the array have the same type. You set the type of Item. The first and the last element in the array is of the same type.
  4. Use any of the following transforms to set the value of a JSON array:
    • Use the For Each transform to set the JSON array output value when you have a repeating input element. For more information, see For Each.
    • Use the Append transform to add occurrences of the array in the order of the inputs to the transform, which can be singleton or repeating. For more information, see Append.
    • Use the Join transform when you have multiple repeating input elements that you must combine into a single repeating output element. For more information, see Join.

Example

This sample shows how to model in a message map the following JSON array. The JSON array is created as an element of a JSON object message:
{"Message":["valueA","valueB"]}
To define this JSON message, you must
  1. Add a user-defined element of type JSONArray_Default, and change its name to Message.
  2. Set the type of Item to string.
The following figure shows the map after you complete the previous steps:

Figure that shows a JSON array.

The message tree for the JSON array in a JSON message is described in the following trace: 

(0x01000000:Object):JSON       = ( ['json' : 0x2f0312d0]
    (0x01000000:Object):Data = (
      (0x01001000:Array):Message = (
        (0x03000000:NameValue):Item = 'valueA' (CHARACTER)
        (0x03000000:NameValue):Item = 'valueB' (CHARACTER)
       )   
     )
)

When you use a For Each transform to set the value of the array elements, notice the difference of how the output message is created. The output differs based on how you connect the input and output elements. In this example, you can see how to transform an input message with two email addresses.

When you wire the transform to the element Item of type string, you get one array with multiple output elements:

Figure that shows the For Each transform to transform a JSON array.

The following code is the message map representation of the JSON array as shown in the previous figure:

     (0x01001000:Array    ):element1      = (
        (0x03000000:NameValue):Item = 'myfirstemail@bbloggs.com' (CHARACTER)
        (0x03000000:NameValue):Item = ' mysecondemail@bbloggs.com' (CHARACTER)
      )
The JSON array that is created has two elements:
"element1":["myfirstemail@bbloggs.com"," mysecondemail@bbloggs.com"]

When you wire the transform to the element element1 of type JSONArray_1, you get two arrays with the same name in the output:

Figure that shows the For Each transform to transform a JSON array.

The following code is the message map representation of the JSON array as shown in the previous figure:

 (0x01001000:Array    ):element1      = (
        (0x03000000:NameValue):Item = 'me@bbloggs.com' (CHARACTER)
      )
      (0x01001000:Array    ):element1      = (
        (0x03000000:NameValue):Item = ' mysecond@bbloggs.com' (CHARACTER)
      )
The JSON elements that are created are two arrays with the same name:
"element1":["myfirstemail@bbloggs.com"],"element1":[" mysecondemail@bbloggs.com"]

What to do next

Deploy the message map and verify that the output message is valid. For more information, see Troubleshooting a message map.