Configuring z/OS Connect Enterprise Edition for CICS managed services

z/OS® Connect Enterprise Edition 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>transportSecurity-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.

   If you use the CICS service provider that is supplied with z/OS Connect Enterprise Edition V2, configure the following elements in server.xml:

   1. Define either a local CICS connection, or a remote IPIC connection.
      The following example definition is for a local CICS connection:

      <zosconnect_cicsLocalConnection id="eciTest"/>

      The following example definition is for a remote IPIC connection:

      <zosconnect_cicsIPICConnection
          id="eciTest" 
          host="cicshost.company.com" 
          port="1111"/>

   2. Enable deployment of services by using SAR files:
      For example,

      <zosconnect_services
          pollingRate="5s" 
          updateTrigger="polled">

   For more information about configuring the z/OS Connect Enterprise Edition CICS service provider, see Using the CICS service provider in z/OS Connect Enterprise Edition V3.0 product documentation.

4. 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.

5. Create an XML pipeline configuration file. Sample pipeline configuration file jsonzosconnectprovider.xml is provided in the directory /usr/lpp/cicsts/cicsts55/samples/pipelines/ (where /usr/lpp/cicsts/cicsts55 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.

6. 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.

7. 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.

8. 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.