Map the API Response fields

Follow the steps to map the responses from your z/OS® Asset to your API Responses.

Before you begin

The following tasks must be completed:
  1. Prepare the sample CICS application.
  2. Starting the z/OS Connect Designer with Docker Desktop and importing an OpenAPI definition.
  3. Configure IPIC connections to CICS with Docker Desktop and Basic Authentication.
  4. Define the GET operation for the /items path.
  5. Reuse the catalogProgram z/OS Asset.
  6. Map the API Request to the z/OS Asset.
  7. Define the POST /orders responses.

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 POST /orders 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

  1. Open the POST /items Operation flow diagram as described Mapping your API and z/OS Assets.
    An amber exclamation mark An amber exclamation mark indicates that the mapping is not defined.
    The OpenAPI definition defines three possible response codes for the POST /orders operation, 200, 400®, and 500. In the following steps, you map the data that is returned from the z/OS Asset to the API responses.
  2. Map the 200 - OK response.
    1. In the Operation flow diagram, click the 200 response node.

      A 200 response code indicates that the requested catalog item to be ordered has been successfully ordered. The item order needs to be mapped to the fields of the API response.

      Figure 1. 200 OK response to be mapped.
      200 OK response to be mapped.
    2. Map the z/OS Asset response input CA-RESPONSE-MESSAGE to the message API response field.

      Type CA-RESPONSE-MESSAGE.

      Figure 2. Mapping CA-RESPONSE-MESSAGE.
      Mapping CA-RESPONSE-MESSAGE.
  3. Map the 400 - Bad Request response.
    1. In the Operation flow diagram, click the 400 response node.

      A 400 response code indicates that the requested catalog item to be ordered has failed due to stock being unavailable.

    2. Input Insufficient stock to complete order into the message field. 
      Insufficient stock to complete order
      Figure 3. Inputting message.
      Inputting message.
  4. 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 a mapping icon insert-mapping icon to select the wanted inputs.
    Figure 4. The completed 500 Internal Server Error API response.
    The completed 500 Internal Server Error API response.

Results

You have successfully mapped the OpenAPI responses (200, 400, and 500) returned by the z/OS Asset.

What to do next

Test the POST /orders operation.