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

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