Defining responses

Set conditions for your OpenAPI definitions responses.

About this task

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


  1. Open the Operation flow diagram as described Mapping your API and z/OS Assets.
  2. Click Responses on the Operation flow diagram.
    Figure 1. Responses.
    Responses within the Operation flow diagram
    The imported OpenAPI definition defines the responses for the operation. If the responses node has one of the following icons, configuration steps are required.
    • An amber exclamation mark An amber exclamation mark indicates that the response condition is not defined.
    • A red mark A warning icon indicates that a response condition is invalid.
    Responses are evaluated from top to bottom where the final response is the default response. Each response case has the following properties:
    • Each condition has three fields, response, predicate, and value,
    • One or more conditions can be applied. Click Add condition + to add a new condition.
    • The ordering of the responses cases can be changed by using An arrow pointing up icon and An arrow pointing down icon next to each response case.
    • The sequence of the conditions within a response case can be changed. Click A drag vertical icon and then drag the condition up and down the condition sequence order to change the conditions place in the sequence.
    • Conditions can be deleted. Click A trash can icon to delete a condition.
    • When response conditions are matched, the mappings for this response are used. If an error occurs when trying to use these mappings, the mapping sources are updated to remove the zosAssetResponse and to add the error details to the error object. The response conditions mappings is then reevaluated (once only), from top to bottom. This retry behavior occurs a maximum of one time.
  3. Define the condition for Response 200 - OK.
    Response 200 means that data was successfully returned and the condition can be defined as shown in Figure 2.
    Figure 2. Response 200
    Response 200
  4. Define the condition for Response 404 - Not Found.
    The Response Field, Predicate, and Value fields are the same as for all Responses. Select the values required for your condition definition. For example, if you'd like to return the 404 not found response when no data is returned in the z/OS Asset response, you can use the $count function. The $count function counts the number of items in an array parameter.
    $count($zosAssetResponse.body."ResultSet Output")
    By setting Predicate to Equals and the value to 0 you can identify when nothing has been returned in the ResultSet Output as per Figure 3.
    Figure 3. Setting the condition for the 404 Response.
    Setting the condition for the 404 response case.
  5. Define the condition for Response 500 - Internal Server Error.
    Normally, the 500 response would be the default, so it is only necessary to ensure that it is the last response in the table. If you want to define the conditions for the 500 response, use the drop-down option to specify how you want the conditions to be evaluated. There are two options, All the following are true indicates that all conditions specified must be true before the 500 response is sent. Any of the following are true indicates that any one of the conditions that are specified must be true before the 500 response is sent. Next, click into the Response Field input box and select the Insert a mapping icon input button to view the Response Field available mapping inputs.
    Figure 4. Response 500 - setting response field input
    Setting response field input for the 500 response code

    Explore the available inputs as shown in Figure 2. An extension to the example in Figure 2 might be to expand the zosAssetResponse mapping and scroll through the list to select statusCode. When the Response Field has been selected, choose the predicate for your condition. In this example, the Equals selection has been kept in the Predicate drop down. Finally, within the Value text box enter the value of 500.

    A summary is displayed to show the condition created, for example, If $zosAssetResponse.statusCode equals 500 then send 500 response for the example above.


IBM® z/OS Connect has new powerful visual-mapping with JSONata expression language. You can complete complex mappings like splits and joins, and other type functions provide huge flexibility. Find out more about these mapping capabilities here How to use JSONata in the z/OS Connect Designer.

What to do next

Now that you have defined your responses that are returned by the API and set the conditions and data mappings, you can test your conditions by using the test features. Find out more about testing your operation here Test the GET /employees/{id} operation.