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.
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 outparameters, 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.
- Define a zosConnectDataXform element in the server.xml
file.
<!-- z/OS Connect data transformation provider -->
<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.
<!-- z/OS Connect service definition -->
<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-1.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