CICS as a service provider for JSON requests using z/OS Connect for CICS

For CICS® to provide a service to an external JSON client, it must receive the request into a z/OS® Connect for CICS, transform the JSON message, and pass it to the target application program. The response from the application is returned to the JSON client through the same mechanism.

Figure 1 shows an example configuration of the architecture and resources that are required to process a request from an external JSON client when CICS is a service provider that uses z/OS Connect for CICS.

Figure 1. The architecture and resources for a JSON service provider that uses z/OS Connect for CICS
The figure show a service requester that is external to the CICS region initiating a request to a CICS application program using z/OS Connect for CICS. The CICS region that the application program runs in also contains the URIMAP, PIPELINE, and WEBSERVICE resources; the pipeline and its handlers and a JVM server.

Processing a JSON request with z/OS Connect for CICS

To process a request, CICS completes the following operations:
  1. Receive the request from the service requester.

    WebSphere® Liberty receives the request and passes it to z/OS Connect for CICS.

  2. CICS resolves the URIMAP resource for the request, by scanning the URIMAP definitions with a USAGE attribute set to JVMSERVER. The URIMAP identifies the WEBSERVICE resource that is used. A new CICS task is started to process the request by using the transaction ID from the URIMAP. By default, the CPIH transaction is used.

    The WEBSERVICE resource controls the processing that CICS performs. In particular, the WSBind file pointed to by the WEBSERVICE resource is used for data transformation between JSON and structured application data. WSBind files for JSON web services are generated by using utilities DFHLS2JS and DFHJS2LS.

    Note: Runtime validation of JSON data against schema is not supported. The value of the VALIDATION attribute of a WEBSERVICE resource that is used with a JSON payload is ignored.
    For information about any restrictions that apply, see JSON web service restrictions.
  3. z/OS Connect for CICS processes the request according to how it is configured. If z/OS Connect for CICS is configured to use global interceptors, the interceptors run during this processing.
  4. The CICSEndpoint receives control. The JSON payload is transformed to structured application data according to the configuration option specified in the pipeline configuration file. There are two options for how the transformation is performed:
    • Java™ transformation is performed within the JVM server. This processing is eligible for offload to a zAAP processor if one is available.
    • Non-Java transformation is performed outside of the JVM server and might provide performance and throughput benefits for certain workloads. For more information about which workloads might benefit, see the performance material that is made available with this release.

    The mapping is performed according to the information in the WSBind file. The output from the transform is equivalent in both cases.

  5. CICS links to the application program and passes the transformed data. The program processes this input and returns a response to the JSON generator.
  6. The JSON generator generates a JSON response message by using the output from step 5. This message is sent back to the service requester via z/OS Connect for CICS.
z/OS Connect for CICS also provides a RESTful interface that supports the standard RESTful methods:
  • POST
  • PUT
  • GET
  • DELETE
  • HEAD
Where appropriate, this interface uses the transform and generator that the pipeline is configured for, in the same way as do normal JSON requests. For more information about RESTful JSON web services, see Concepts of RESTful JSON web services.

Most of the z/OS Connect for CICS infrastructure processing is eligible for offloading onto a zEnterprise® Application Assist Processor (zAAP).