After initially configuring z/OS® Connect for CICS®, you can configure it for a CICS JSON web service. JSON web services are deployed to z/OS Connect for CICS in a similar way
as to other CICS PIPELINE environments.
Before you begin
You must complete the basic configuration of z/OS Connect before you start this task. For
z/OS Connect for CICS 1.0, see
Configuring z/OS Connect for CICS 1.0.
For
z/OS Connect Enterprise Edition, see
Configuring z/OS Connect Enterprise Edition. You also require a JSON WSBind file for each
service you want to deploy; these binding files
can be generated by using the CICS JSON assistant
(the
DFHLS2JSand
DFHJS2LS utility programs).
For more information on these utility programs,
see
The CICS JSON assistant.
About this task
JSON web services are deployed to z/OS Connect for
CICS in a similar fashion to how they are deployed to other
CICS PIPELINE environments.
Procedure
- Install a WEBSERVICE resource that associates the WSBind file with the appropriate PIPELINE
resource. Select a meaningful name for the WEBSERVICE, as this name is also used as the name of the
Service in z/OS Connect. Optionally, you can use the
PERFORM PIPELINE SCAN command to install WEBSERVICE resources. Whichever method
you choose to use, ensure that you consider the following information about URIMAPs:
The URI, at
which the Service is available within z/OS Connect, is taken
from one of the following locations:
- The default naming convention that is used by z/OS
Connect itself.
- The URI stored in the WSBind file, when the associated WEBSERVICE resource is installed by using
the PERFORM PIPELINE SCAN command.
- The Service specific configuration in the Liberty server.xml file, if the
invokeURI configuration parameter is used.
- z/OS Connect Enterprise Edition only: The Application
Archive File (.aar file) for
an API that encapsulates the Service.
If you rely on the default naming convention, the Service is typically exposed through
the following URI:
https://<hostname>:<port>/zosConnect/services/<Service Name>?action=invoke
In
this example,
<Service Name> refers to the name of the Service (more
specifically, the name of the WEBSERVICE resource), and
<hostname> and
<port> are taken from the configuration of the Liberty server.
- Optional: Install a URIMAP resource for the z/OS Connect
Service. A URIMAP resource is used by CICS to associate the work
for the Service with a specific transaction ID in CICS, and
an initial User ID. You can use a single URIMAP to configure one or many Services. You might also define a default
URIMAP resource when you configure CICS for z/OS Connect. If no URIMAP exists to match the URI for a z/OS Connect Service, the application's tasks run under transaction
CJSA, and the CICS default user ID
(typically CICSUSER) is used as the initial user ID. For more information about the role of the
initial User ID, see Configuring permissions for z/OS Connect Services and APIs.
If you choose to create a
URIMAP resource, ensure that the associated user ID has authority to run the
specified transaction.
You might also choose to use a URIMAP to associate the URI with a
specific WEBSERVICE resource. If a URIMAP is tightly bound to a WEBSERVICE, the target WEBSERVICE is
used for all HTTP requests that are matched by the URIMAP. If a WEBSERVICE is not specified, the
WEBSERVICE is selected based on the name of the z/OS Connect
Service. If the WEBSERVICE attribute of the URIMAP is left blank, z/OS Connect performs the mapping itself, which allows z/OS Connect Enterprise Edition to associate different Services
with different HTTP methods within an API.
- Optional: Update the server.xml file Some usage patterns might require changes in the Liberty server configuration file,
server.xml. It is usually not necessary to make Service-specific changes in the
server.xml file, unless you require special-case processing for a Service. For
example, you might choose to associate a specific set of z/OS
Connect interceptors with a Service in the server.xml file, or expose a Service
by using a URI that does not match the z/OS Connect default
naming convention.
Use these steps to define a Service in the server.xml
file:
- Ensure that the intended Service name does not match the name of a WEBSERVICE resource in CICS. CICS automatically
injects configuration information into z/OS Connect, and if
an explicitly defined Service and a CICS WEBSERVICE have the
same name, the resultant behavior is unpredictable.
- Set a suitable value for the invokeURI attribute in
the server.xml file that matches the URI used in the URIMAP.
- Bind the Service to the CICSEndpointService
serviceRef element.
- Ensure that a URIMAP exists to match the URI for the Service to the precise WEBSERVICE that is
to be used. If an invokeURI attribute is set in Step b.,
the URIMAP must match that URI. Otherwise, the URIMAP must assume the z/OS Connect default URI naming convention.
The following example shows an explicit z/OS Connect
for CICS 1.0 Service declaration in the
server.xml file:
<zosConnectService invokeURI="/json/myCustomService"
serviceName="CICSService1"
serviceRef="com.ibm.cics.wlp.zosconnect.CICSEndpointService"/>
The following example shows the equivalent declaration for z/OS Connect Enterprise Edition in the server.xml file:
<zosconnect_zosConnectService invokeURI="/json/myCustomService"
serviceName="CICSService1"
serviceRef="com.ibm.cics.wlp.zosconnect.CICSEndpointService"/>
In both examples, the "/json/myCustomService" URI is associated with the z/OS Connect for CICS
receiver program, CICSService1.
Results
You can test the configuration for z/OS Connect for
CICS by
typing this URL into a web browser:
https://hostname:portnumber/zosConnect/apim/services.
The
hostname is the IP address
or name of the CICS region that hosts z/OS Connect for CICS. The
portnumber is the
httpsPort that is configured
in the
<httpEndpoint>
section of the
server.xml
configuration file. The web browser displays a
list of the installed services.
The service is
now ready to be called from a JSON client that
uses the same hostname and
portnumber.
Each
installed Service has an entry in the
zosConnect/apim/services list,
for
example:
{
"id":"EXAMPLE",
"name":"EXAMPLE",
"url":"https://hostname:portnumber/zosConnect/apim/services/EXAMPLE",
"protocol":"REST",
"description":"CICS Service"
}
In
this example, the associated WEBSERVICE resource
was named
"EXAMPLE", and this
Service definition was created dynamically by CICS
when the
EXAMPLE WEBSERVICE
resource was installed. You can use a web browser
to visit
https://hostname:portnumber/zosConnect/apim/services/EXAMPLE
that returns a document with more details about
the Service, similar to the
following:
{
"id":"EXAMPLE",
"name":"EXAMPLE",
"protocol":"REST",
"description":"CICS Service",
"restEndpoints":[
{
"name":"EXAMPLE",
"address":"hostname:portnumber/jsonTests/myExampleService"
}
]
}
In
this example, the "address" is
the URI at which the Service is exposed. This URI
might be derived from information in a WSBind
file, from an invokeURI
attribute, or from the default z/OS Connect naming
convention.
When a request arrives in the
Liberty JVM server, it is associated with the z/OS Connect
for CICS
receiver that uses the information from the
server.xml configuration
file. A new CICS task starts to perform this work, and
it is associated with a specific WEBSERVICE
resource that uses the information from the URIMAP
resource. The data transformation process occurs
in the Liberty JVM server, and the target CICS program is
attached, as named in the WSBind file.