Using the WOLA service provider

Follow these steps to use the WOLA service provider supplied with IBM® z/OS® Connect .

Before you begin

The WebSphere® Optimized Local Adapter (WOLA) service provider requires that both the zosconnect:zosconnect-2.0 and the zosLocalAdapters-1.0 features are configured. The WOLA service provider is included with IBM z/OS Connect and uses the WOLA function provided with the Liberty profile. The WOLA service provider can be used by both WOLA-enabled applications and CICS® (to support IBM z/OS Connect V2 configurations).

About this task

IBM z/OS Connect provides a service implementation that allows IBM z/OS Connect requests to interact with z/OS assets through WOLA. The service is automatically enabled when both zosconnect:zosconnect-2.0 and the zosLocalAdapters-1.0 features are configured. Instances of this service can be defined through the zosconnect_localAdaptersConnectService configuration element.

Procedure

For a service to use the WOLA service provider, the service definition requires a zosconnect_localAdaptersConnectService configuration element in the server.xml file.

The minimum configuration consists of the target WOLA Connection Factory name, Register name (RGN), and Service name. Configuration of IBM z/OS Connect follows the Liberty profile conventions by only requiring the minimum parameters to be specified.

For more information about all the supported attributes, see zosconnect_localAdaptersConnectService in the Reference section.

The only supported authentication mechanism on a WOLA connection factory is container managed authentication. The authentication credentials are defined using an authData element that is referenced on the containerAuthDataRef attribute of the connectionFactory element.

WOLA uses a three part name to uniquely identify the WOLA server. This name is derived from the wolaGroup, wolaName2 and wolaName3 attribute values on the local adapter's configuration element zosLocalAdapters, and must be unique per server in the same z/OS LPAR.

The following code snippet is an example of configuring the WOLA service provider:

<!-- z/OS Connect service definitions -->
<zosconnect_zosConnectService id="zcs1"
serviceName="recordOpsCreate"
serviceRef="wolaOpsCreate"/>

<!-- 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 -->
<zosconnect_localAdaptersConnectService id="wolaOpsCreate"
	registerName="BATCH01"
	serviceName="COBLPGM1"
	connectionFactoryRef="wolaCF"/>

The IBM z/OS Connect service implementation that allows IBM z/OS Connect requests to interact with z/OS assets through 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 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.

The WOLA service provider implementation allows for a number of other WOLA connection factory attributes to be specified in its zosconnect_localAdaptersConnectService configuration element.

You can specify the way for a WOLA CICS Link Server to propagate data to target CICS application programs by using the useCICSContainer attribute in the localAdaptersConnectService element. When the useCICSContainer attribute is set to false, the payload is passed to the target CICS application program by using a COMMAREA; otherwise, the payload is passed to the target CICS application program by using CICS containers.

The following options are supported to flow payloads to CICS application programs:

Use a COMMAREA.
Use a channel name of IBM-WAS-ADAPTER to flow a single payload container.
Use a channel name of your choice to flow a single payload container with the HTTP context containers. The context containers pass information about the HTTP request to the CICS application program. See Table 1 for more information.

Table 1. HTTP context container names and descriptions
Name	Description
`ZCONReqURL`	Contains the URL of the HTTP request. For example, if an `invokeURI` definition of /banking/deposit and a query parameter `country=USA` are used, the URL is https//localhost: port/banking/deposit?country=USA.
`ZCONReqQParms`	Contains the query parameters of the HTTP request. For example, if a request URL is https//localhost:port//banking/deposit?country=USA, the query parameter is `country=USA`.
`ZCONReqMethod`	Contains the method of the HTTP request, for example, `GET`.
`ZCONHTTPHeaders`	Contains a JSON-formatted set of HTTP header name and value pairs that is configured by using the `linkTaskChanCtxContHttpHeaders` attribute under the `zosconnect_localAdaptersConnectService` element.