Configuring z/OS Connect for CICS 1.0

z/OS® Connect for CICS® 1.0 is distributed as part of CICS Transaction Server. You must configure a JVM server and set up the pipeline configuration and resources for z/OS Connect, before you can deploy JSON services. This initial configuration is a one-time activity.

1. Create a JVMSERVER and configure it to support the WebSphere Liberty. For more information about creating a WebSphere Liberty JVMSERVER, see Configuring a Liberty JVM server.
2. Configure WebSphere Liberty for your security requirements. By default, WebSphere Liberty expects the use of client-certified SSL certificates. To enable HTTP Basic Authentication, add the following configuration option to the server.xml file:

       <!-- Allow fail-over to HTTP Basic Authentication --> 
       <webAppSecurity allowFailOverToBasicAuth="true"/>

   You must also give users of z/OS Connect the zosConnectAccess security role. For more information about WebSphere Liberty security, see Configuring security for a Liberty JVM server, and for z/OS Connect security, see Security for z/OS Connect.
3. Update the <featureManager> list in the server.xml file for the WebSphere Liberty environment to include a <feature>cicsts:zosConnect-1.0</feature> feature, as shown in the following example:

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

4. Define the z/OS Connect for CICS 1.0 Service Controller by adding the following statement to the server.xml file:

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

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 returned by z/OS Connect for CICS 1.0, such as the following:

   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). You must decide whether you want to parse the JSON by using Java™ in the Liberty JVM server (which is 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 1.
   • 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.
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 information, see Pipeline configuration files.
8. Create a PIPELINE resource.
   The PIPELINE resource defines the location of the pipeline configuration file in the CONFIGFILE attribute.
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 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. The initial user ID is only in effect until user-specific authentication happens in z/OS Connect.