How to use JSONata in the z/OS Connect Designer

z/OS Connect Designer enables powerful mapping and data transformation with JSONata. Explore how to use JSONata with z/OS Connect Designer with some "how to" steps and examples.

Before you begin

JSONata is an open source expression language that is used for querying and transforming JSON data. Before starting this topic, the What is JSONata? topic is available as an introduction.

If you are familiar with JSONata, you need an API project open in z/OS Connect Designer with a z/OS Asset that is mapped in the operation.

About this task

This task shows you how to use the new powerful visual-mapping UI in z/OS Connect to use JSONata expression language. You can complete complex mappings like splits and joins, and other type functions provide huge flexibility.
JSONata is used in the following mapping definitions:
z/OS Asset request mapping
Figure 1. z/OS Asset request mapping
Click the z/OS Asset node to edit the mapping for the request.
Defining Response conditions

The Responses node in the z/OS Connect Designer allows a user to define which response is returned by the API, depending on the response from the z/OS Asset. You can set conditions for each response within an API operation.

Each response condition row (Response field, Predicate, Value fields) in z/OS Connect Designer Responses node is converted to a JSONata expression. When more than one response condition is defined for a response, they are joined using either boolean AND or boolean OR, depending on the selected Rule combination, to form a single JSONata expression.

The JSONata expressions are evaluated in the order that they appear in the response_mapping.yaml file and return true or false. When true is returned, the response case is used. When false is returned, the next response condition is evaluated. The last response condition is always true and acts as a default.

The Response field can contain one or more response conditions that can be complex JSONata expressions or select a single field as shown in Figure 2.
Note: When using ternary operators, the value needs to be wrapped in parentheses.

For more information about JSONata expression operators, such as the conditional ternary operator, see JSONata Other Operators.

Figure 2. Defining Response conditions
Click the Responses node to edit the response conditions.
Mapping individual response codes such as 200, 404, and 500
Figure 3. Mapping individual response codes. This example shows the 200.
Click the specific response node to edit the mapping for that response code. This example shows the 200.
To edit the mapping for a field, start typing the name in that field. Designer displays all the matching fields so you can select the one you want. For example, to map lastName to LASTNAME, click in the lastName field and start typing la. z/OS Connect Designer Designer shows the matching fields.
Figure 4. z/OS Connect Designer Designer shows the matching fields
z/OS Connect Designer Designer shows the matching fields

You can see that Designer shows not only the field names that start with la, but any fields that contain la, such as SALARY. It also displays any matching functions that are valid in this context.

You can continue typing in a field to add other content. For example, the bio field contains a complete sentence containing several expressions and string literals.
Figure 5. Example of z/OS Connect Designer completing the sentence containing several expressions and string literals.
Screen capture displaying the complete sentence containing several expressions and string literals. "'First name' works in 'Work dept' department. Compensation is 'salary' USD."
As you type, z/OS Connect Designer continues to look for matching names. You can ignore these matches and continue typing or select the field name or function to insert it into the expression. For example,
Figure 6. Example of z/OS Connect Designer looking for matching names for the expression being built.
Screen capture displaying how z/OS Connect Designer continues to look for matching names. In this example the user is partway through typing "as a j" and the results are showing 'Job' as a selectable 'object'.

Procedure

  1. Click the node on the Operation flow diagram where you want to add the JSONata expressions.
    For example, Figure 7 shows the Operation flow diagram for the /GET/employees

    Figure 7. Operation view of /GET/employees.
    Operation view of /GET/employees.

  2. Click each response node to define the rules for the operation responses with JSONata expressions.
    1. Click Responses.
    2. Each response can be set as All the following are true or Any of the following are true.
    3. Click Add condition + to add another condition for the response.
    4. Click A trash can icon to remove response conditions.
    5. Click An arrow pointing down icon or An arrow pointing up icon to change the response case sequence.
  3. Click Test to check whether the output matches your requirements.
    By using z/OS Connect Designer, you can enter a JSONata expression, then click Test to see whether the output matches your requirements. If not, you can modify the expression and test again. By repeating this process, you can gradually build up the expression to suit your needs.

What to do next

For more examples about what is possible with JSONata, see Sample JSONata expressions.