In the Graphical
Data Mapping editor,
you can use the Add User-Defined function
to create a JSON message that contains JSON objects, JSON arrays,
or both.
About this task
If you have a JSON schema
model, you can use it in your map in a shared library or REST API;
for more information, see Creating or transforming a JSON message by using a JSON schema. If
you do not have a JSON schema model, you can create a map selecting
the predefined JSON message and define your JSON data by using the Add
User-Defined function as described in this topic.
Note: You
cannot use both JSON schema and user-defined elements a message body.
However, you can create a map that has the input message body defined
by JSON schema, and the output message or local environment defined
by using the Add User-Defined function.
Procedure
Complete the following steps to create a JSON message
for which you do not have a schema model:
- Create a message map.
Select one of the following JSON supplied models as the input or output
of the map:
- JSON (JSON object message model supplied by IBM) to
create a JSON object message
- JSON (JSON array message model supplied by IBM) to
create a JSON array message
- Qualify the content under the Data element
by using the Add User-Defined function.
A JSON message consists of name-value pairs, which
are known as JSON objects, and ordered collections of
values, which are known as JSON arrays.
- To define a JSON object in the JSON output message, use the Add User-Defined function to add an
element, and select one of the supported simple types.
For more information, see Graphically modeling a JSON object in a message map.
- To define a JSON array in the JSON output message, use the Add User-Defined function to add an
element, and select JSONArray_Default as
its type. For more information, see Graphically modeling a JSON array in a message map.
- To define a multidimensional JSON array in the JSON output message,
use the Add User-Defined function
to add multiple elements, and select JSONArray_Default as
their types. For more information, see Graphically modeling a multidimensional JSON array in a message map.
Note: When you use the Graphical
Data Mapping editor to transform a
JSON message, ensure that the JSON element names that
you define by using the Add User-Defined function
are valid according to the XML rules for naming elements.
JSON allows a wider range of characters than XML, for
example a JSON object might include the @ character,
however, the Graphical
Data Mapping editor allows
only element names that are valid in XML or XPath.
- Define transforms between the input elements and the output
elements.
- Use the Assign transform to set a fixed
value without the use of input data.
- Use the Create transform to create
an empty JSON object, or a NULL JSON object, without the use of input
data
- Use the Move transform to copy an input
element value to the output element.
- Use the If transform, a custom transform,
or the XPath transform to define
the condition that determines the value of an output element.
- Use the Append transform, the Group
transform, the For Each transform,
the Join transform, a custom
transform, or the XPath transform
to set the value of a JSON array.
- Use the Select transform or the Database
Routine transform to set the value with
data available in a database system.
- Use the xs:type transform to cast the
value of a simple input element to a specific data type.
- Use the fn:type transform to set the
value by using XPATH 2.0 functions.
- Use the Custom Java transform to enter
your own Java™ code.
- Use the Custom ESQL transform
to call your own ESQL code.
- Use a Custom XPath transform with the
function
iib:nullValue()
to set a JSON object to
NULL, or a JSON array to NULL.
Example
This example shows how to model in a
message map the
following JSON object message:
{"element1":[{"Nam":"val1","Num":1},{"Nam":"val2","Num":2}]}
To define this JSON message, you must
- Add a user-defined element of type JSONArray_Default,
and change its name to Message.
- Set the type of Item to Anonymous.
- Add two elements that represent the object-value elements in the
array. The display name in the map is representative of
the name of the object. At run time, the Graphical
Data Mapping editor uses the name of
the objects that are passed in the message.
The following figure shows the map after you complete the previous
steps:
The message tree for
the JSON message is described in the following trace:
(0x01000000:Object):JSON = ( ['json' : 0x2f030fa0]
(0x01000000:Object):Data = (
(0x01001000:Array):element1 = (
(0x01000000:Object):Item = (
(0x03000000:NameValue):Nam = 'val1' (CHARACTER)
(0x03000000:NameValue):Num = 1 (INTEGER)
)
(0x01000000:Object):Item = (
(0x03000000:NameValue):Nam = 'val2' (CHARACTER)
(0x03000000:NameValue):Num = 2 (INTEGER)
)
)
)
)
This other example shows how to model
in a
message map the following JSON array
message:
[{"element1":{"field1":"Sweet","field2":"Flower"},"element2":"me@bbloggs.com"}]
The message tree for the JSON array
message is described in the following trace:
(0x01000000:Object):JSON = ( ['json' : 0x292051a0]
(0x01001000:Array):Data = (
(0x01000000:Object):Item = (
(0x01000000:Object ):element1 = (
(0x03000000:NameValue):field1 = 'Sweet' (CHARACTER)
(0x03000000:NameValue):field2 = 'Flower' (CHARACTER)
)
(0x03000000:NameValue):element2 = 'me@bbloggs.com' (CHARACTER)
)
)
What to do next
Deploy the message map and verify that the output
message is valid. For more information, see Troubleshooting a message map.