Map the API response fields

Map the responses from your z/OS® Asset to your API Responses.

Before you begin

The following tasks must be completed:

About this task

This topic is applicable to: z/OS Connect Designer
capability Content applicable to
application developers

The z/OS Asset response fields need to be mapped to the API response fields. In the task Define the GET /items responses, you defined the order in which the response codes are checked. The next step is to map the data that is returned for each response code.

Procedure

Open the GET /items Operation flow diagram as described in Mapping your API and z/OS Assets.
An amber exclamation mark indicates that the mapping is not defined.
The OpenAPI definition defines two possible response codes for the GET /item operation, 200 and 500. In the following steps, you map the data that is returned from the z/OS Asset to the API responses.
Map the 200 response.

In the Operation flow diagram, click the 200 response node.

A 200 response code indicates that the requested catalog items were found and the information is returned in an array. The item record properties need to be mapped to the fields of the API response.

Figure 1. 200 OK response to be mapped.
1. Map the z/OS Asset response input CA-ITEM-COUNT to the totalItems API response field.
  Type CA-ITEM-COUNT.
  
  Figure 2. Mapping CA-ITEM-COUNT.
2. Map the returned CA-CAT-ITEM array from the z/OS Asset to the items array in the API response.
  Within the items mapping input, use one of the following methods
  - Select the CA-CAT-ITEM node from the Input selection window.
  - Enter the following command into the field.
    $zosAssetResponse.commarea.DFH0XCP1."CA-INQUIRE-REQUEST"."CA-CAT-ITEM"
  Figure 3. Mapping the CA-CAT-ITEM array.
  
  This configuration iterates over the returned CA-CAT-ITEM array that contains the list of items and maps the fields for each item within the array.
3. Map the API response stock field with the summary structure.
  Use JSONata to create a complex mapping that describes the state of the stock by using multiple response fields from the z/OS Asset.
  Figure 4. Complex stock API response field mapping.
  Within the stock API response field, use one of the following methods to create the complex mapping from the z/OS Asset:
  Method 1 - While the field is active write:
  
  Enter Department.
  
  Select the CA-DEPARTMENT node from the input select window.
  
  Enter has.
  
  Select the IN-STOCK node from the input select window.
  
  Enter a single space.
  
  Select the CA-DESCRIPTION node from the input select window.
  
  Enter apostrophes around the CA-DESCRIPTION node to show where the description begins and ends.
  
  Enter in stock.
  Method 2 - Enter
  
  Department {{$item."CA-DEPARTMENT"}} has {{$item."IN-STOCK"}} '{{$item."CA-DESCRIPTION"}}' in stock.
  Figure 5. Completed complex stock API response field mapping.
4. Map the API response orders field.
  Use JSONata to create a complex mapping that describes the state of the order by using multiple response fields from the z/OS Asset and JSONata expressions to manipulate the data.
  The CICS program always returns 15 items in the CA-CAT-ITEM array, even if there are not 15 items details to be included. Use JSONata to check the CA-COST field is not an empty string before it is cast to a number using the $number function.
  
  Figure 6. Complex orders API response field mapping.
  Within the order API response field, use one of the following methods to create the complex mapping from the z/OS Asset:
  Method 1 - While the field is active, enter:
  
  Select the ON-ORDER node from the input select window.
  
  Select the CA-DESCRIPTION node from the input select window.
  
  Enter apostrophes around the CA-DESCRIPTION node so show where the description begins and ends.
  
  Enter on order at unit price of $ .
  
  Enter two sets of curly brackets {{ }}. This enables the use of an expression.
  
  Select the $length() expression node from the input JSONata expression window with CA-COST node from the input select window as the argument.
  
  Enter = 0 ? 0 : . This is a ternary expression to check whether CA-COST is an empty string before casting it to a number.
  
  Select the $number() expression node from the input JSONata expression window with CA-COST node from the input select window as the argument.
  
  Enter . Total order value: $ .
  
  Enter two sets of curly brackets {{ }}. This enables the use of an expression.
  
  Select the $length() expression node from the input JSONata expression window with CA-COST node from the input select window as the argument.
  
  Enter = 0 ? 0 : This is a ternary expression to check whether CA-COST is an empty string before casting it to a number.
  
  Between the curly brackets select the $number() expression node from the input JSONata expression window with CA-COST node from the input select window as the argument .
  
  Still between the curly brackets, enter *.
  
  Still between the curly brackets, select the $number() expression node from the input JSONata expression window with ON-ORDER node from the input select window as the argument .
  
  Method 2 - Enter
  
  {{$item."ON-ORDER"}} '{{$item."CA-DESCRIPTION"}}' on order at unit price of ${{$length($item."CA-COST") = 0 ? 0 : $number($item."CA-COST")}}. Total order value: ${{$length($item."CA-COST") = 0 ? 0 : $number($item."CA-COST") * $number($item."ON-ORDER")}}
  Figure 7. Completed complex orders API response field mapping.
Map the remaining API response fields.
In the same way as the previous steps, you can choose to map the corresponding fields between the z/OS Asset and the API response.

Use the ternary expression to check whether CA-COST is an empty string or not before casting it to a number within the cost response field.
```
{{$length($item."CA-COST") = 0 ? 0 : $number($item."CA-COST")}}
```
Figure 8. The completed 200 OK API response.
Map the 500 - Internal Server Error response.
In the Operation flow diagram, click the 500 response node.
A 500 response code indicates an internal server error. Configure the 500 response to return the z/OS Connect error message and the contents of the CA-RESPONSE-MESSAGE field by inputting the following into the message field:
```
{{$error.message}}{{$zosAssetResponse.commarea.DFH0XCP1."CA-RESPONSE-MESSAGE"}}
```
Alternatively you can build up the mapping. Click the insert-mapping icon to select the wanted inputs.

Figure 9. The completed 500 Internal Server Error API response.

Results

The OpenAPI responses (200 and 500) returned by the z/OS Asset are successfully mapped.

What to do next

Test the GET /items operation.