Configuring Data Transformers

IBM® IBM z/OS® Connect provides the ability to optionally transform request and response payloads that are used for calling a business asset on z/OS operating systems. You can create message payload transformers to satisfy specific needs by implementing the com.ibm.zosconnect.spi.DataXform Service Provider Interface (SPI), which is included with IBM z/OS Connect.

About this task

IBM z/OS Connect provides an implementation that requires the request and response message format be JSON. This product supports the conversion of the request to a byte array, which can be mapped by a native language COBOL, PL/I, or C structure. This language structure of the target program, or copy book, includes a description of the in and out parameters. The language structure is used by a supplied utility to generate a binding file and JSON request and response schema files. The bind file that is generated by this utility is used by IBM z/OS Connect to complete the data conversion to and from JSON and native data formats as requests arrive and responses are returned. You can retrieve the JSON schemas for the request and response message with a RESTful API call that is provided by IBM z/OS Connect.

IBM z/OS Connect provides the zosConnectService configuration element that enables the administrator to configure a set of attributes that apply to a particular service. One of these attributes is dataXformRef, which points to a data transformation configuration that is to be used for a specific service. This task describes how the data transformer supplied with IBM z/OS Connect is used.

Note:
  1. In the examples shown in steps 1 & 2, the serviceName and bindFileSuffix must match the bindfile found in bindFileLoc. For example: recordOpsCreate.wsbind resides in /u/bindfiles.
  2. The request and response schema file names must match the serviceName specified in the zosConnectService element with _request or _response appended. The values, including the file type, must match the requestSchemaSuffix or responseSchemaSuffix respectively. For example: recordOpsCreate_request.json and recordOpsCreate_response.json. These files must reside in /u/json.

Procedure

  1. Update the zosConnectService element for each service in your server.xml configuration for which you want to enable the data transformation supplied by IBM z/OS Connect.
    <!-- z/OS Connect service definition --> 
    <zosconnect_zosConnectService id="zcs1" 
    	serviceName="recordOpsCreate" 
    	serviceRef="wolaOpsCreateService" 
    	dataXformRef="xformJSON2byte"/> 
    
  2. Create the associated zosConnectDataXform element.
    <!-- z/OS Connect data transformation provider --> 
    <zosconnect_zosConnectDataXform id="xformJSON2byte" 
    		bindFileLoc="/u/bindfiles" bindFileSuffix=".wsbind" 
    		requestSchemaLoc="/u/json" responseSchemaLoc="/u/json"
    		requestSchemaSuffix=".json" responseSchemaSuffix=".json"/>  
    
  3. Optional: Configure a data transformer that applies to all services.
    Set the globaDataXformRef of the zosConnectManager element to the configured data transformer's ID that is intended for global use. If both global and service data transformers are defined and requests come in for a service with a configured data transformer, IBM z/OS Connect will use the data transformer configured specifically for the service.
    <zosconnect_zosConnectManager globalDataXformRef="globalDataXform"/>   
    
    <!-- z/OS Connect data transformation provider --> 
    <zosconnect_zosConnectDataXform id="globalDataXform" 
    		bindFileLoc="/u/bindfiles" bindFileSuffix=".wsbind"         
    		requestSchemaLoc="/u/json" responseSchemaLoc="/u/json"
    		requestSchemaSuffix=".json" responseSchemaSuffix=".json"/>