Defining z/OS Connect services

z/OS® Connect service definitions provide the mechanism for reaching z/OS application assets using REST calls. To enable z/OS Connect services, you must add a z/OS Connect service definition to the Liberty server.xml file with the element name zosConnectService along with a name and service provider reference element name.

About this task

z/OS Connect services are defined by the zosConnectService configuration element. This element contains attribute definitions that may have globally defined counterparts. Attributes can be defined globally through the zosConnectManager element. These attributes, if defined, apply to all services. If both global and service level attributes are configured, the values defined at the zosConnectService level are used.

z/OS Connect provides a service implementation that allows z/OS Connect requests to interact with z/OS assets through WebSphere Optimized Local Adapters (WOLA). The service is automatically enabled when both zosConnect-1.0 and the zosLocalAdapters-1.0 features are configured. Instances of this service can be defined through the localAdaptersConnectService configuration element.

z/OS Connect also provides a service implementation that allows z/OS Connect requests to contact a remote REST endpoints. The service is available when the zosConnect-1.2 feature is configured. Instances of this service can be defined through the zosConnectServiceRestClient configuration element. For more information, see the documentation for the z/OS Connect REST Client Service.

Stabilized features: The zosConnect-1.0 and zosConnect-1.2 features are stabilized. You can continue to use the features. However, consider using the IBM z/OS Connect Enterprise Edition product.

Procedure

Add a zosConnectService configuration element for each service in your server.xml configuration.
You must configure the serviceRef and serviceName attributes at minimum. The serviceRef element points to the service provider configuration element. The serviceName attribute is how the service provider identifies itself with z/OS Connect and is also the name to use as part of the URL for z/OS Connect requests that are targeted to a specific service. The service name must be unique. The following is a sample server.xml file that shows what is required to add a z/OS Connect service called recordOpsCreate. Note that a more complete example is shown in step 3.
```
 
<zosConnectService id="zcs1"  
	serviceName="recordOpsCreate"  
	serviceRef="wolaOpsCreate"/> 
```
For more information about the configurable attribute definitions associated with the zosConnectService element, see the documentation for the z/OS Connect feature.
(Optional) Add the zosConnectManager configuration element to the server.xml file.
This element is a singleton in the server.xml configuration and it contains global values that apply to all z/OS Connect services that are defined for the server. The element can contain the names of z/OS Connect interceptors or data transformation provider configuration elements that apply to all services in the server.

The following example describes a zosConnectManager configuration element that defines an operations group name of Operator1 under the item globalOperationsGroup. This is the name of the security (SAF or LDAP) group that the requesting client userid needs to be in before z/OS Connect operations requests are permitted, such as action=start|stop|status. This group applies to all services in the z/OS Connect configurations. The item dataxform defines the element name where z/OS Connect will find a data transformation provider. Supplying the dataxform in the zosConnect element means this is the transformation provider implementation for all services in the configuration that do not already have their own data transformation element reference. The interceptors item is the name of the element in the configuration that describes the set of z/OS Connect interceptors that apply to all services in the configuration.
```
<zosConnectManager id="zosConnectGlobals"  
	globalOperationsGroup="Operator1"  
	globalDataxformRef="XformJSON2Byte"  
	globalInterceptorsRef="GlobalInterceptors"/> 
```
For more information about the configurable attribute definitions associated with the zosConnectManager element, see the documentation for the z/OS Connect feature.
For more information on each attribute, see the Liberty features documentation.

If WOLA is configured in Liberty, the configuration for a request requires a localAdaptersConnectService configuration element in the server.xml file.

This configuration consists minimally of the target WOLA Connection Factory name, Register name and Service name. Configuration of z/OS Connect follows the Liberty conventions by only requiring the minimum parameters to be specified. Note, when you configure a WOLA connection factory for z/OS Connect interaction, you must use container as the authentication mechanism. WOLA connection factories that do not specify a containerAuthDataRef attribute are not supported. The following is an example:

<!-- Local adapters connection factory definition --> 
<authData id="cauth1" user="user1" password="{xor}LDo8Ki02KyY="/> 
<connectionFactory id="wolaCF" jndiName="eis/ola"        
	containerAuthDataRef="cauth1"  >       
	<properties.ola/> 
</connectionFactory>     

<!-- Local adapters config --> 
<zosLocalAdapters wolaGroup="LIBERTY" wolaName2="LIBERTY"         
	wolaName3="LIBERTY" /> 

<!-- WOLA Connect service and z/OS Connect service definitions --> 
<localAdaptersConnectService id="wolaOpsCreate"             
	registerName="BATCH01"   
	serviceName="COBLPGM1"   
	connectionFactoryRef="wolaCF"/> 

<zosConnectService id="zcs1" serviceName="recordOpsCreate"    
	serviceRef="wolaOpsCreate"   
	runGlobalInterceptors="true"    
	interceptorsRef="serviceInterceptorList"
        dataXformRef="zconXform"/> 

<!-- z/OS Connect data transformer --> 
<zosConnectDataXform id="zconXform"          
	bindFileLoc="/zosConnect/bind" 
        bindFileSuffix=".bnd"   
	requestSchemaLoc="/zosConnect/schema"  
	responseSchemaLoc="/zosConnect/schema"
	requestSchemaSuffix=".json"
	responseSchemaSuffix=".json">
</zosConnectDataXform>

The z/OS Connect service implementation that allows z/OS Connect requests to interact with z/OS assets through WebSphere Optimized Local Adapters (WOLA) might require a data transformer. If a data transformer is configured, globally or at the service level, input and output payloads are converted using the configured data transformer. If a data transformer is not configured, and the request contains a JSON payload, the service assumes that the backend program will handle the data conversion. The service converts the JSON payload, as is, to a byte array using the encoding specified in the request header or the default JSON encoding of UTF-8. Similarly, if the asset returns a payload and no data transformer is configured, the WOLA service implementation expects to receive a JSON payload in byte array form, which is converted to a JSON response payload following the same encoding rules used for transforming a JSON request payload to a byte array.

When linkTaskChanID is configured along with useCICSContainer=true under the localAdaptersConnectService element, a set of context containers and a payload container are sent to the destination program. The following list provides the names and description of the context containers.

ZCONReqURL: The ZCONRegURL context container contains the HTTP request URL. For example, if you use an invokeURI definition of /banking/deposit and query parameter country=USA, the URL is https//localhost:port/banking/deposit?country=USA.
ZCONReqQParms: The ZCONReqQParms context container contains the HTTP request query parameters. For example, with request URL https//localhost:port//banking/deposit?country=USA, the query parameter is country=USA.
ZCONReqMethod: The ZCONReqMethod context container contains the HTTP request method. For example, GET.
ZCONHTTPHeaders: The ZCONHTTPHeaders context container contains a JSON formatted set of HTTP header name and value pairs that are configured by using the linkTaskChanCtxContHttpHeaders attribute under the localAdaptersConnectService element.

The linkTaskChanCtxContHttpHeaders attribute accepts a list of comma separated case sensitive strings that represent the header names to be passed to the destination program in the ZCONHTTPHeaders container. The information contained in this context container is in JSON format, for example,

{httpHeaders:{"header1":"header1Value",
...,"headerN":"headerNValue"}}

. If the request contains multiple headers with the same name, the value used is the value for the first header in the request.

Users can modify the default encoding of the data (cp819) that is contained in all context containers by using the linkTaskChanCtxContEncoding configuration attribute under the localAdaptersConnectService element.

When linkTaskChanID is configured along with useCICSContainer=true under the localAdaptersConnectService element, you can customize the input and output container payload names by using the linkTaskChanReqContID and linkTaskChanRespContID attributes. If these attributes are not defined, the default names are ZCONReqData and ZCONRespData. The following example illustrates proper configuration.

<localAdaptersConnectService id="wolaOpsCreate"
        registerName="OLASERVER"
        serviceName="ZCONMC5"
        connectionFactoryRef="wolaCF"
        linkTaskChanID="ZCONCHANNEL"
        linkTaskChanType="1"
        useCICSContainer="true"
        linkTaskChanCtxContHttpHeaders="Connection, CustomHeader1, CustomHeader2, CustomHeader3"
        linkTaskChanReqContID="wolaOpsReqData"
        linkTaskChanRespContID="wolaOpsRespData"
        linkTaskChanCtxContEncoding="cp037"/>

The following table is a list of localAdaptersConnectService attribute definitions and a description of each.

Attribute Definition	Description
`serviceName` `required="true"` `type="String"`	Name of the WOLA target service. The `serviceName` must match the name an external address space application is using for the service name on a WOLA Receive Request or Host Service API call, or the program name used for SVC with a WOLA CICS Link Server.
`registerName` `required="true"` `type="String"`	Name of the WOLA target registration. This name must match the name an external address space application is using for the register name on a WOLA Register API call, or the name used for RGN with a WOLA CICS Link Server. The `registerName` can be any alphanumeric string of 1 to 12 characters.
`connectionFactoryRef` `required="true"` `type="String"`	Reference to the configured WOLA resource adapter connection factory.
`connectionWaitTimeout` `required="false"` `type="Integer"` `min="0"` `max="2147483647"`	Time to wait in seconds for an external address space application that matches the registration name to issue a WOLA Receive Request or Host Service API and become active. This attribute defines the `ConnectionWaitTimeout` property on the Optimized Local Adapters connection factory. If a value is not specified, the default value for the property is used. Refer to the Connection factory properties for optimized local adapters on Liberty documentation for more information.
`linkTaskTranID` `required="false"` `type="String"`	Defines the name of the WOLA CICS Link Server link invocation task transaction ID (Any 4-character string). This attribute is used when using the CICS Link Server. This attribute defines the `LinkTaskTranID` property on the Optimized Local Adapters connection factory. Refer to the Connection factory properties for optimized local adapters on Liberty documentation for more information.
`useCICSContainer` `required="false"` `type="Boolean"` `default="false"`	Defines the mechanism to use for data propagation. When set to true, the payload is passed to the target CICS application program using CICS containers. When set to false (default), the payload is passed the target CICS application program using a COMMAREA. This attribute is used when using the CICS Link Server. This attribute defines the `useCICSContainer` property on the Optimized Local Adapters connection factory. Refer to the Connection factory properties for optimized local adapters on Liberty documentation for more information.
`linkTaskReqContType` `type="Integer"` `min="0"` `default="0"`	Defines the type of the request container (0=CHAR, 1=BIT). This attribute is used when using the CICS Link Server and when the linkTaskReqContID and useCICSContainer (true) attributes are also configured. This attribute defines the linkTaskReqContType property on the Optimized Local Adapters connection factory. Refer to the Connection factory properties for optimized local adapters on Liberty documentation for more information.
`linkTaskRspContID` `required="false"` `type="String"`	Defines the name of the response, or output, container (A string of 1 to 16 characters that matches the container name defined to CICS). This attribute is used when using the CICS Link Server and when the linkTaskReqContID and useCICSContainer (true) attributes are also configured. This attribute defines the linkTaskRspContID property on the Optimized Local Adapters connection factory. Refer to the Connection factory properties for optimized local adapters on Liberty documentation for more information.
`linkTaskRspContType` `type="Integer"` `min="0"` `default="0"`	Defines the type of the response container (0=CHAR, 1=BIT). This attribute is used when using the CICS Link Server and when the linkTaskRspContID and useCICSContainer (true) attributes are also configured. This attribute defines the linkTaskRspContType property on the Optimized Local Adapters connection factory. Refer to the Connection factory properties for optimized local adapters on Liberty documentation for more information.
`linkTaskChanID` `required="false"` `type="String"`	Defines the CICS channel name to use for delivering and receiving payloads using CICS containers using a string of 1 to 16 characters that matches the channel name defined to CICS. This attribute is used when using the CICS Link Server and when the useCICSContainer (true) attribute is also configured. This attribute defines the linkTaskChanID property on the Optimized Local Adapters connection factory. Refer to the Connection factory properties for optimized local adapters on Liberty documentation for more information.
`linkTaskChanType` `required="false"` `type="Integer"` `min="0"` `default="0"`	Defines the type of CICS containers (0=CHAR, 1=BIT) that are to be associated with the configured channel ID. When set to 0=CHAR (default), the encoding of the character data in the input/output containers are expected/returned in ASCII (CCSID 819) and the data is converted to or from EBCDIC (cp037) before/after it is sent to/from the destination program. Use the BIT type avoid data type and encoding expectations. This attribute is used when using the CICS Link Server and when the linkTaskChanID and useCICSContainer (true) attributes are also configured. This attribute defines the linkTaskChanType property on the Optimized Local Adapters connection factory. Refer to the Connection factory properties for optimized local adapters on Liberty documentation for more information.
`linkTaskChanReqContID` `required="false"` `default="ZCONReqData"` `type="String"`	Defines the name of the request container using a string of 1 to 16 characters that matches the container name defined to CICS. This attribute is used when using the CICS Link Server and when the linkTaskChanID and useCICSContainer (true) attributes are also configured.
`linkTaskChanRespContID` `required="false"` `default="ZCONRespData"` `type="String"`	Defines the name of the response container using a string of 1 to 16 characters that matches the container name defined to CICS. This attribute is used when using the CICS Link Server and when the linkTaskChanID and useCICSContainer (true) attributes are also configured.
`linkTaskChanCtxContEncoding` `required="false"` `type="String"` `default="cp819"`	Defines the encoding of the data in all context containers that are sent to the destination program. This attribute is used when using the CICS Link Server and when the linkTaskChanID and useCICSContainer (true) attributes are also configured.
`linkTaskChanCtxContHttpHeaders` `required="false"` `type="String"`	Defines the HTTP header name or list of comma-separated HTTP header names that are passed to the destination program using the context container with the name of ZCONHTTPHeaders. The information contained in this context container is in JSON format as follows: `{httpHeaders:{"header1":"header1Value", ...,"headerN":"headerNValue"}}`. This attribute is used when using the CICS Link Server and when the linkTaskChanID and useCICSContainer (true) attributes are also configured.