Configuring z/OS Connect Enterprise Edition

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.

Before you begin

Install the z/OS Connect Enterprise Edition run time. Follow the instructions in the z/OS Connect Enterprise Edition documentation in IBM Knowledge Center, but be aware that tailoring z/OS Connect Enterprise Edition to run embedded within CICS means that you do not need to create a separate Liberty server instance. You only need it installed to the extent that the file system components are available on zFS. Installing the API Editor that is supplied with z/OS Connect Enterprise Edition is not part of this task.

Have you previously installed z/OS Connect for CICS 1.0? If so, several of the steps in this task are not necessary. The steps that you can skip are indicated in the list.

Procedure

  1. Add ZCEE_INSTALL_DIR to your JVM server options. For more information about the option and an example, see JVM server options.
  2. 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.

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

  3. Configure WebSphere Liberty for your security requirements. By default, it 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.

    Start of changeIf you previously installed z/OS Connect for CICS 1.0, you can skip this step because you are likely to have a suitable configuration already. End of change

  4. Update the <featureManager> list in the server.xml file for the WebSphere Liberty to include a <feature>cicsts:zosConnect-2.0</feature> feature, as shown in the following 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 are migrating from z/OS Connect for CICS 1.0 to z/OS Connect Enterprise Edition, change the existing cicsts:zosConnect-1.0 feature to cicsts:zosConnect-2.0.
  5. Define the z/OS Connect 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"/> 

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

  6. 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 Enterprise Edition such as the following:
    SRVE0169I: Loading Web Module: z/OS Connect.
    SRVE0250I: Web Module z/OS Connect has been bound to default_host.
  7. 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 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 previously installed z/OS Connect for CICS 1.0, you can skip this step because you are likely to have a suitable configuration already.

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

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

  9. Create a PIPELINE resource. The PIPELINE resource defines the location of the pipeline configuration file in the CONFIGFILE attribute.

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

  10. Optional: Start of changeCreate 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. Specifying a specific User ID such as ZOSCUSER in the URIMAP is recommended, rather than relying on the default CICS User ID to be used (typically "CICSUSER"), and authorising it to use the target Transactions.

    End of change

Results

Your z/OS Connect Enterprise Edition instance is configured. You can test the basic configuration for z/OS Connect by typing this URL into a web browser: https://hostname:portnumber/zosConnect/apim/services, where hostname is the IP address or host name of the system on which the CICS region that is hosting z/OS Connect is running, and portnumber is the httpsPort that is specified in the <httpEndpoint> element of the server.xml file. The web browser displays a list of installed services: this list is empty, because no services are installed yet.

Start of changeIf you receive an HTTP 403 "AuthorizationFailed" response rather than the expected Service list, review the Security configuration from Step 3. It is likely that the authenticated user is not authorized to use z/OS Connect.End of change

What to do next

You are now ready to deploy JSON web services or APIs into z/OS Connect Enterprise Edition. For information about deploying services, see Configuring z/OS Connect for a CICS JSON web service. For information about deploying APIs, see Using APIs from z/OS Connect Enterprise Edition.


zos_connect_ee_configuring.html | Timestamp icon Last updated: Sunday, 4 June 2017