Getting started with z/OS Connect
z/OS® Connect enables CICS® programs to be called with a JavaScript Object Notation (JSON) interface. z/OS Connect for CICS 1.0 was first introduced as an alternative to the JSON capabilities of the Java™ Pipelines for JSON that were provided in the CICS TS Feature Pack for Mobile Extensions and integrated into CICS TS Version 5.2. Since then, z/OS Connect has grown into a separate product, called z/OS Connect Enterprise Edition, with additional capabilities. These topics describe the differences between the alternative offerings and the steps towards implementation.
z/OS Connect is IBM®'s premier technology for implementing JSON services and APIs in CICS. It is available in three versions, and supports several deployment options. z/OS Connect for CICS 1.0 is the entry level edition and a low-cost option, but lacks the enhancements of the other versions. z/OS Connect Enterprise Edition version 2.0 and 3.0 offer a further range of integration options.
For an overview of JSON services, see CICS as a service provider for JSON requests.
z/OS Connect Enterprise Edition
z/OS Connect Enterprise Edition is a separately-orderable IBM product. It builds on the capabilities of z/OS Connect for CICS 1.0, which included support for JSON services. z/OS Connect Enterprise Edition enables API developers to construct JSON APIs from JSON services. The APIs are constructed and packaged with the Eclipse-based API Editor that is provided with z/OS Connect EE, then deployed to the z/OS Connect runtime. The API package includes Swagger 2.0 definitions to make it easier for developers to incorporate the APIs into their applications. Key z/OS Connect capabilities, such as authorization security checking for service invocation, creation of System Management Facility (SMF) records, and logging of RESTful service requests also apply to the APIs.
- If you use z/OS Connect Enterprise Edition V2.0, use
the CICS service provider that is supplied with CICS TS and feature
cicsts:zosConnect-2.0. This configuration enables local, high-performance connectivity to CICS programs. This is the only supported service provider for z/OS Connect Enterprise Edition V2.0. - If you use z/OS Connect Enterprise Edition V3.0 to
connect to a local CICS region, use the CICS service provider that is supplied with z/OS Connect Enterprise Edition V3.0 and feature
zosconnect:cicsService-1.0. This configuration uses a local, optimized connection to the local CICS region. - If you use z/OS Connect Enterprise Edition V3.0 to
connect to a remote CICS region, use the CICS service provider that is supplied with z/OS Connect Enterprise Edition V3.0 and feature
zosconnect:cicsService-1.0. This configuration uses an IP interconnectivity (IPIC) connection to a remote CICS region.
JSON services that were developed for use with z/OS Connect for CICS 1.0, and most JSON services that were developed for use with Java Pipelines for JSON, can be hosted in z/OS Connect Enterprise Edition. See z/OS Connect for CICS 1.0 for more details. However, users of the API Editor that is supplied with z/OS Connect Enterprise Edition should be aware of some restrictions. For details, see Using APIs from z/OS Connect Enterprise Edition.
For more information, see z/OS Connect Enterprise Edition V3.0 product documentation.
z/OS Connect for CICS 1.0
z/OS Connect for CICS 1.0 is a no-charge feature provided in CICS TS from Version 5.2. It is broadly equivalent to the Java Pipelines for JSON and most JSON web services can be redeployed from one environment to the other without changes to applications or WSBind files. However, the URI and security configuration can be different in each environment. JSON web services that are deployed to z/OS Connect for CICS 1.0 can also be deployed to z/OS Connect Enterprise Edition.
- z/OS Connect for CICS 1.0 supports only the deployment of JSON web services for CICS. It cannot be used to target other z/OS subsystems such as IMS or Batch.
- z/OS Connect for CICS 1.0 integrates with CICS resources. JSON web services are deployed using WEBSERVICE and URIMAP resources.
- JSON service-enablement techniques from the Java Pipelines for JSON are supported with z/OS Connect for CICS 1.0, including those that are not normally available in z/OS Connect.
- JSON services can be developed by using both bottom-up and top-down development strategies.
- JSON web services generated for Java Pipelines for JSON can be redeployed to z/OS Connect for CICS 1.0.
Earlier technologies
Other JSON technologies for CICS precede z/OS Connect including the Feature Pack for
Mobile Extensions
and JSON services
. The Mobile Extensions Feature Pack 1.0 worked with
CICS TS for z/OS
Version 5.1 and Version 4.2. The Feature Pack provided the capability to expose CICS applications as RESTful web services with JSON payloads, call existing JSON
applications, and convert JSON to and from application data. From Version 5.2, this capability was
integrated into CICS TS. Services deployed for the older
technologies are usually compatible with z/OS Connect. However, z/OS Connect Enterprise Edition provides the best experience
for new services and APIs.
Deployment options for z/OS Connect Enterprise Edition
- Standalone z/OS Connect Enterprise Edition
- Connectivity to CICS is achieved using either IPIC or WOLA connections from an external address space. For further information, see Configuring in the z/OS Connect Enterprise Edition product documentation.
- z/OS Connect Enterprise Edition V3 in a CICS JVMSERVER hosting z/OS Connect administered services and APIs
- z/OS Connect Enterprise Edition V3.0 is hosted within a Liberty JVM server in CICS, and communication is achieved over a locally optimized IPIC connection. Services are created using rich UI driven tooling, and deployed using SAR and AAR files. This configuration option is very similar to that of Option 1, except that it is hosted within the CICS address space.
- z/OS Connect Enterprise Edition in a CICS JVMSERVER hosting CICS administered services (compatibility mode)
- This option is available for any version of z/OS Connect. It offers a hybrid mode in which services formerly deployed for CICS JSON services technology are aggregated into z/OS Connect. WSBind files are created using the DFHLS2JS or DFHJS2LS JCL procedures, deployed to CICS as WEBSERVICE resources, but installed into z/OS Connect by CICS. This configuration option brings many of the advantages of z/OS Connect Enterprise Edition to the older style of JSON services, though some limitations and differences in capability will be experienced.
Comparing z/OS Connect capabilities
This section compares the capabilities of z/OS Connect Enterprise Edition and z/OS Connect for CICS 1.0. A comparison for the Java Pipelines for JSON (or the Feature Pack for Mobile Extensions) is also included because it preceded z/OS Connect for CICS 1.0.
| Capability | z/OS Connect Enterprise Edition | z/OS Connect for CICS 1.0 | Java Pipelines for JSON (or the Feature Pack for Mobile Extensions) |
|---|---|---|---|
| Support for standard z/OS Connect capabilities | Yes. Service Discovery requires extra configuration. | Yes. Service Discovery requires extra configuration. | No |
| Enable CICS programs as JSON web services | Yes | Yes | Yes |
| Support for RESTful JSON services | Yes | Yes | Yes |
| Support for RESTful APIs | Yes | No | No |
| Support for starting remote JSON services | V3: Yes; V2: No, Use DFHJSON | No. Use DFHJSON. | No (use DFHJSON) |
| Support for CICS data transformation that uses the DFHLS2JS and DFHJS2LS assistants | Yes. See Note 1. | Yes | Yes |
| Support for SAR based Service deployment | V3: Optional; V2: No | No | No |
| Support for JSON schema specification | Yes (draft-04) | Yes (draft-04) | Yes (draft-04) |
| Choice of parser technologies for JSON transformation | Yes | Yes | No |
| Support for PIPELINE handler programs | No | No | Yes |
| Support for interceptor programs | Yes, by using z/OS Connect Interceptors | Yes, by using z/OS Connect Interceptors | Yes, by using Axis2 handlers |
| Application access to CICS control containers | Yes | Yes | Yes |
| WSBind deployment through a CICS PIPELINE resource | V3: Optional; V2: Yes. See Note 2 | Yes | Yes |
| Configuration with URIMAP and WEBSERVICE resources | V3: Optional; V2: Yes. See Note 3 | Yes | Yes |
| Network configuration | Using WebSphere® Liberty | Using WebSphere Liberty | Using a TCPIPSERVICE resource |
| Security configuration | Using WebSphere Liberty and CICS security | Using WebSphere Liberty and CICS security | Using CICS |
| Support for Transport Layer Security (TLS) | Yes | Yes | Yes |
| Statistics, monitoring, user exits, and other diagnostics infrastructure | Consistent with WebSphere Liberty in CICS | Consistent with WebSphere Liberty in CICS | Consistent with pipelines in CICS |
| JVM environment | A Liberty JVM server that is preferably isolated for sole use by z/OS Connect | A Liberty JVM server that is preferably isolated for sole use by z/OS Connect | A non-OSGi JVM server configured with JAVA_PIPELINE=YES, preferably isolated for sole use by the Java Pipelines for JSON |
- If you use the CICS service provider that is
supplied with CICS TS, then this capability is supported for
services. For APIs, use the assistants that are supplied by z/OS Connect Enterprise Edition.
If you use the CICS service provider that is supplied with z/OS Connect Enterprise Edition V3.0, this capability is not supported. Use the z/OS Connect Enterprise Edition API Toolkit, or the build toolkit to create services and then use the API toolkit to create APIs.
- If you use the CICS service provider that is
supplied with CICS TS, then this capability is supported for
services, but deploying APIs involves additional artifacts. For more information, see the z/OS Connect Enterprise Edition documentation.
If you use the CICS service provider that is supplied with z/OS Connect Enterprise Edition V3.0, this capability is not supported for services. Use the z/OS Connect Enterprise Edition services directory. Deploying APIs involves additional artifacts. For more information, see the z/OS Connect Enterprise Edition documentation.
- This capability is supported for services, only if you use the CICS service provider that is supplied with CICS TS. The CICS service provider that is supplied with z/OS Connect Enterprise Edition V3.0 supports the manual creation of URIMAPs. You can use a URIMAP, for example, to override the default CICS transaction (CJSA).