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.
Before you begin
Do you already have a WebSphere® Liberty
JVM server that is configured in CICS? Although
it is possible to host z/OS® Connect and other
unrelated services in the same WebSphere
Liberty environment, it is good practice to configure a separate JVM server for the sole
use of z/OS Connect. It is also good practice to
have only a single WebSphere Liberty JVM
server that is configured in any single CICS
region.
You can host z/OS Connect for CICS 1.0 in its
own CICS region, or group of CICS regions, and use the Distributed Program Link
mechanism to call CICS programs in the
application-owning CICS regions.
Procedure
- 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.
- 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.
- 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>
- 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"/>
- 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.
- 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.
- 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.
- Create a PIPELINE
resource. The PIPELINE resource defines the location of the pipeline configuration file
in the CONFIGFILE attribute.
- 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 more 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 within z/OS Connect.

Results
Your
z/OS Connect for CICS 1.0
instance is configured. You can test the basic configuration 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 for CICS 1.0 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; because no services are yet installed, the list is
empty.
If you receive an HTTP 403 "AuthorizationFailed" response rather than the
expected Service list, review the Security configuration from Step 2. 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 into
z/OS Connect for CICS 1.0.