Defining z/OS Connect message payload transformations

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 can be created to satisfy specific needs by implementing the com.ibm.wsspi.zos.connect.DataXform Service Provider Interface (SPI), which is included with z/OS Connect.

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.

About this task

z/OS Connect provides an implementation that requires the request and response message format be JSON. This feature 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, which includes a description of the in and out parameters, is used to generate a binding file, and JSON request and response schema files by using a z/OS Connect-provided utility. The binding file that is generated by this utility is used by 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 REST API call that is provided by z/OS Connect.

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 to request that the z/OS Connect-supplied data transformer be used.

Procedure

Define a zosConnectDataXform element in the server.xml file.
```
 
<zosConnectDataXform id="zosConnectXform"
	bindFileLoc="/zosConnect/banking/bind/" 
        bindFileSuffix=".bnd" 
        requestSchemaLoc="/zosConnect/banking/reqSchema" 
        requestSchemaSuffix=".json"
	responseSchemaLoc="/zosConnect/banking/respSchema" 
        responseSchemaSuffix=".json"/>  
```
Using this example, all file location related attribute definitions, such as bindFileLoc, requestSchemaLoc, and responseSchemaLoc are specified for completeness. Only the bindFileLoc and requestSchemaLoc attribute definitions are required. If the responseSchemaLoc attribute is not configured, the value of the requestSchemaLoc attribute is used.

Using the same example, all suffix related attribute definitions, such as <bindFileSuffix>, <requestSchemaSuffix>, and <responseSchemaSuffix> are specified for completeness. They are all optional. If they are not specified, the bind and schema files to be loaded by z/OS Connect will not be expected to have a suffix.
z/OS Connect expects data transformation related files to have a specific format based on the configuration.
- bind files: <serviceName><bindFileSuffix>
- request schema files: <serviceName>_request<requestSchemaSuffix>
- response schema files: <serviceName>_response<requestSchemaSuffix>
Using the following zosConnectService sample configuration and the previous zosConnectDataXform sample configuration.
```
 
<zosConnectService id="zosConnectCustomer" 
	serviceName="customer" 
	serviceRef="wolaCustomerCreate" 
	dataXformRef="zosConnectXform"/> 
```
The name of the data transformation files are.
- bind files: customer.bnd
- request schema files: customer_request.json
- response schema files: customer_response.json
For more information about the configurable attribute definitions associated with the zosConnectDataXform element, see the documentation for the z/OS Connect feature.

Update the zosConnectService element for each service in your server.xml configuration for which you want to enable the z/OS Connect-supplied data transformation.

<!-- z/OS Connect service definition --> 
<zosConnectService id="zosConnectCustomer" 
	serviceName="customer" 
	serviceRef="wolaCustomerCreate" 
	dataXformRef="zosConnectXform"/>

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, z/OS Connect will use the data transformer configured specifically for the service.


<zosConnectManager id="zosConnectGlobalDefinitions
        globalDataXformRef="zosConnectGlobalDataXform"/>   

<!-- z/OS Connect data transformation provider --> 
<zosConnectDataXform id="globalDataXform" 
	bindFileLoc="/zosConnect/banking/bind/"
        bindFileSuffix=".bnd"         
        requestSchemaLoc="/zosConnect/banking/reqSchema"
        requestSchemaSuffix=".json" 
        responseSchemaLoc="/zosConnect/banking/respSchema"
        responseSchemaSuffix=".json"/>

Optional: Configure settings such as pollingRate and updateTrigger to fine tune the monitoring actions.
By default, the directories associated with a data transformation definition are monitored for new files and file updates. For more information about these configuration attributes see the zosConnectDataXform element section under z/OS Connect 1.0 and z/OS Connect 1.2.
```
<zosConnectDataXform id="globalDataXform" 
        bindFileLoc="/zosConnect/banking/bind/"
        bindFileSuffix=".bnd"         
        requestSchemaLoc="/zosConnect/banking/reqSchema"
        requestSchemaSuffix=".json" 
        responseSchemaLoc="/zosConnect/banking/respSchema"
        responseSchemaSuffix=".json"
        pollingRate="500ms"> 
</zosConnectDataForm>      
```
In the example, directories /zosConnect/banking/bind,/zosConnect/banking/reqSchema, and /zosConnect/banking/respSchema are polled for file updates every 500 milliseconds. If the pollingRate and updateTrigger configuration attributes are not configured, the default values of polled and 2 seconds are used, respectively. If you do not need file monitoring, you can disable it by setting the updateTrigger attribute to disabled. If you prefer to trigger a manual refresh of certain files, set the updateTrigger attribute to mbean and use file notification mbean: com.ibm.ws.kernel.filemonitor.FileNotificationMBean to trigger the updates; for example:
```
String[] MBEAN_METHOD_SIGNATURE = new String[] {Collection.class.getName(),Collection.class.getName(),Collection.class.getName() };        
JMXConnector jmxConnector = ...;        
MBeanServerConnection mbsc = jmxConnector.getMBeanServerConnection();        
ObjectName fileMonitorMBeanName = new ObjectName("WebSphere:service=com.ibm.ws.kernel.filemonitor.FileNotificationMBean");        

List<String> paths = new ArrayList<String>();        
paths.add("/zosConnect/banking/bind/customer.bnd");        
paths.add("/zosConnect/banking/reqSchema/customer_request.json");       
paths.add("/zosConnect/banking/respSchema/customer_response.json");        

Object[] params = new Object[] { null, paths, null };        
mbsc.invoke(fileMonitorMBeanName, "notifyFileChanges", params, MBEAN_METHOD_SIGNATURE);
```
The example uses the restConnector-2.0 feature to trigger the update of files customer.bnd, customer_request.json, and customer_response.json. For more information about how to create a secure JMX connection see the documentation on Configuring secure JMX connection to Liberty