Configuring z/OS Connect Enterprise Edition V2 for CICS managed services

z/OS® Connect Enterprise Edition V2 is a separately orderable product; it is not supplied as part of CICS® TS. First, you must install the runtime component of z/OS Connect Enterprise Edition and configure a zFS file so that CICS can locate it. Then, you configure a JVM server and set up the pipeline configuration and resources for z/OS Connect before you can deploy JSON services and APIs. This initial configuration is a one-time activity that allows z/OS Connect Enterprise Edition to run embedded in the Liberty server that is distributed with CICS TS.

1. Ensure that all the steps in Configuring z/OS Connect Enterprise Edition are complete.
2. Update the <featureManager> list in the server.xml file to include the cicsts:zosConnect-2.0 feature.
   For example,

   
       <featureManager>
           <feature>cicsts:core-1.0</feature>
           <feature>ssl-1.0</feature>
           <feature>cicsts:zosConnect-2.0</feature>
       </featureManager>

   Note: z/OS Connect for CICS 1.0 and z/OS Connect Enterprise Edition features are mutually exclusive. If you upgrade from z/OS Connect for CICS 1.0 to z/OS Connect Enterprise Edition, you must change the feature.
3. Define the z/OS Connect Service Controller.
   If you use the CICS service provider that is supplied with CICS TS, add the following statement to the server.xml file:

   
       <com.ibm.cics.wlp.zosconnect.CICSEndpoint 
           id="com.ibm.cics.wlp.zosconnect.CICSEndpointService"/> 

   If you have z/OS Connect for CICS 1.0 installed, you can skip this step because you are likely to have a suitable configuration already.

4. Set the operationMode attribute on the zosconnect_zosConnectManager element to "SYNC".
   The default, asynchronous mode, causes work to be distributed across several threads. In most environments this will result in a better ability to tolerate heavy workloads. Synchronous mode allocates a single thread for the duration of processing for a single request. Use synchronous mode when running a z/OS Connect EE server inside CICS, where each thread is backed with its own CICS task. It avoids multiple tasks being started in CICS during the processing of a request.
5. Install the JVMSERVER. Check the generated messages.log file for error or warning messages.
   This log contains the messages that are generated by WebSphere® Liberty Server, including messages that are issued by z/OS Connect Enterprise Edition such as:

   SRVE0169I: Loading Web Module: z/OS Connect.
   SRVE0250I: Web Module z/OS Connect has been bound to default_host.

6. Create an XML pipeline configuration file. Sample pipeline configuration file jsonzosconnectprovider.xml is provided in the directory /usr/lpp/cicsts/cicsts54/samples/pipelines/ (where /usr/lpp/cicsts/cicsts54 is the default installation directory for CICS files on z/OS UNIX). Decide whether you want to parse the JSON by using Java™ in the Liberty JVM server (the default), or to use the non Java JSON parser.
   • To parse the JSON by using Java in the Liberty JVM server, you can use the sample pipeline configuration file, but replace DFHWLP in the <jvmserver> element with the name of your JVMSERVER from step 2.
   • To parse the JSON by using the non Java parser, modify the sample configuration file to append the java_parser="no" attribute to the <provider_pipeline_json> element as in the following example:

     <?xml version="1.0" encoding="EBCDIC-CP-US"?>
     <provider_pipeline_json java_parser="no" xmlns="http://www.ibm.com/software/htp/cics/pipeline">
         <jvmserver>DFHWLP</jvmserver>
     </provider_pipeline_json>

   Replace DFHWLP with the name of the JVMSERVER that you created at the start of this procedure.

   If you have z/OS Connect for CICS 1.0 installed, you can skip this step because you are likely to have a suitable configuration already.

7. Copy the pipeline configuration file to a suitable directory in zFS and ensure that the file permissions allow the CICS region to read the file.
   For more information, see Pipeline configuration files.

   If you have z/OS Connect for CICS 1.0 installed, you can skip this step because you are likely to have a suitable configuration already.

8. Create a PIPELINE resource.
   The PIPELINE resource defines the location of the pipeline configuration file. Do not attempt to use the SCAN mechanism to install WEBSERVICEs into this PIPELINE.

   If you have z/OS Connect for CICS 1.0 installed, you can skip this step because you are likely to have a suitable configuration already.

9. Optional: Create a default URIMAP resource for z/OS Connect.
   URIMAP resources are used to associate a TRANSACTION and default user ID with z/OS Connect work. One or more URIMAP resources can be used to configure a default policy for z/OS Connect. For an example of URIMAP configuration and more information on configuration options, see Configuring permissions for z/OS Connect Services and APIs.

   Note:

   z/OS Connect performs extra authentication for individual HTTP requests, so the application tasks that run in CICS are typically associated with a more specific User ID than the initial User ID from the URIMAP.

   This initial User ID is only in effect until user-specific authentication happens within z/OS Connect. Use a specific User ID such as ZOSCUSER in the URIMAP, rather than relying on the default CICS User ID to be used (typically "CICSUSER"), and authorizing it to use the target transactions.