Configuring z/OS Connect for CICS for a CICS JSON web service

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.

• 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 in z/OS Connect is taken from one of the following locations:

  • The default naming convention that z/OS Connect uses.
  • 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:

  1. 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.
  2. Set a suitable value for the invokeURI attribute in the server.xml file that matches the URI used in the URIMAP.
  3. Bind the Service to the CICSEndpointService serviceRef element.
  4. 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 was set in Step 2, 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.

{
"id":"EXAMPLE",
"name":"EXAMPLE",
"url":"https://hostname:portnumber/zosConnect/services/EXAMPLE",
"protocol":"REST",
"description":"CICS Service"
}

{
"id":"EXAMPLE",
"name":"EXAMPLE",
"protocol":"REST",
"description":"CICS Service",
"restEndpoints":[
      {
       "name":"EXAMPLE",
       "address":"hostname:portnumber/jsonTests/myExampleService"
      }
   ]
}