Zengin TCP/IP Adapter

How the Zengin TCP/IP Adapter Works

The Zengin TCP/IP adapter uses the Zengin Configuration Import service to populate Zengin TCP/IP adapter configurations into a database. The Zengin Configuration Import service enables the Zengin adapter to function, but is not part of the Zengin TCP/IP adapter. It is created independently. For more information, see Implementing the Zengin Configuration Import Service Configuration.

When the Sterling B2B Integrator server is running, the Zengin Receiver and Responder adapter listens on a port specified in the adapter configuration. Accordingly, when an incoming request is received from a remote Zengin server, the Zengin Receiver and Responder adapter creates a new instance of the Zengin Receiver and Responder adapter to respond to the request and process it.

The following sections explain how the Zengin Sender and Requester adapter and the Zengin Receiver and Responder adapter function.

Zengin Sender and Requester Adapter, Sending a File

View the status report in the Sterling B2B Integrator Business Process Detail window. The following example shows the structure of the status report and the four possible status values:

<ZenginResult>
	<file_alias_1>success</file_alias_1>
	<file_alias_2>fail</file_alias_2>
	<file_alias_3>not sent</file_alias_3>
	<file_alias_4>unknown</file_alias_4> 
</ZenginResult>

Zengin Sender and Requester Adapter, Requesting a File

Zengin Receiver and Responder Adapter, Receiving a File

Zengin Receiver and Responder Adapter, Responding to a File Request

Implementing the Zengin TCP/IP Adapter

Implementing the Zengin Configuration Import Service Configuration

The Zengin Configuration Import service imports the Zengin XML configuration file into the data source. Creating a Zengin XML configuration is a prerequisite step that is required to use the Zengin TCP/IP adapter.

Configuring the Zengin Configuration Import Service

To configure the Zengin Configuration Import service, you must specify field settings in Sterling B2B Integrator.

Sterling B2B Integrator Configuration

The following table describes the fields used to configure the Zengin Configuration Import service in Sterling B2B Integrator:

GPM Configuration

There is no configuration required in the GPM for the Zengin Configuration Import service.

Configuring the File System Adapter

To configure the File System adapter instance for use with the Zengin Configuration Import service, you must specify field settings in Sterling B2B Integrator and in the GPM.

Sterling B2B Integrator Configuration

The following table describes the fields used to configure the required File System adapter instance in Sterling B2B Integrator:

GPM Configuration

The business process runs, respectively, the File System adapter configuration and the Zengin Configuration Import service configuration. The first operation of the business process runs the File System adapter to read the Zengin XML configuration file. Specify the following field settings for the File System adapter in the GPM:

The second operation of the business process runs the Zengin Configuration Import service to extract the configuration from the file into the data source or database. There is no need to specify any specific entry. The following business process is an example of how this operation should look:

<process name="zengin_configuration_import"> 
<sequence name="Main sequence">
	<operation name="File System Adapter">
			<participant name="my_file_sys_adapter_instance"/>
			<output message="FileSystemInputMessage">
				<assign to="Action">FS_COLLECT</assign>
				<assign to="assignedFilename" from=" ‘my_zengin_config_xml'"></assign>
				<assign to="collectionFolder">my_folder</assign>
				<assign to="deleteAfterCollect”>false</assign>
				<assign to="filter" from=‘my_zengin_config_xml'"</assign>
				<assign to="."from="*"></assign>
			</output>
		<input message="inmsg">
				<assign to="."from="*"></assign>
		</input>
	</operation>
	<operation name="Zengin Configuration Import Service>
		<particpant name="my_zengin_config_import_instance"/>
			<output message="output">
				<assign to="."from="*"></assign>
			</output>
			<input message="input">
				<assign to="."from="*"></assign>
			</input>
	</operation> 
</sequence> 
</process>

An example of this business process (ZenginConfigImport.bpml) is available in the installroot/samples/Zengin folder.

Configuring the Zengin XML Configuration File

The XML schema for the Zengin configuration file is defined in the file, zengin-config.xsd, which is included with Sterling B2B Integrator. Find this file in the Sterling B2B Integrator DTD/Schema repository.

The following table describes the format of the elements in the Zengin XML configuration file. You must preconfigure these elements for the Zengin TCP/IP adapter to work properly. Several of the element values are represented as hexadecimal (base 16) numbers because both ROS3 Zengin servers and CJS (Chori Joho Systems) Zengin servers use hexadecimal notation for these elements.

The following sample Zengin XML configuration file defines the required single instance of the local server (<alias>localhost</alias>), a single remote Zengin server (<alias>Ros3</alias>), and two files associated with the ROS3 server:

<?xml version="1.0" encoding="UTF-8"?> 
<zengin xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="zengin-config.xsd">
  <server>
     <zengin_id>
      <alias>localhost</alias>
<!--the local server(Sterling B2B Integrator)-->
      <center_code>1212121212</center_code>
      <cpu_node_code>1A1B</cpu_node_code>
    </zengin_id>
   <client>
       <zengin_id>
           <alias>Ros3</alias>
           <center_code>123456789A</center_code>
           <cpu_node_code>F1F1</cpu_node_code>
       </zengin_id>
       <password>FFFFFFFFFFFF</password>
       <file_definition>
           <file_alias>send_variable_uncompr</file_alias>
           <filename>FOFOFOFOFOFOFOFOFOFOFOFO</filename>
           <request_bp_name>bpreq</request_bp_name>
           <receive_bp_name>bprecv</receive_bp_name>
           <fixed_record_length>false</fixed_record_length>
           <record_length>256</record_length>
           <use_compression>false</use_compression
           <file_access_key>AA00000000AA</file_access_key>
       </file_definition>
       <file_definition>
           <file_alias>send_fixed_uncompr</file_alias>
           <filename>000000000000000000000001</filename>
           <request_bp_name>bpreq</request_bp_name>
           <receive_bp_name>bprecv</receive_bp_name>
           <fixed_record_length>true</fixed_record_length>
           <record_length>256</record_length>
           <use_compression>false</use_compression
           <file_access_key>FE00120000EF</file_access_key>
       </file_definition>
   </client>
  </server> 
</zengin>

Securing the Zengin XML Configuration File

Information is normally stored in the Zengin XML configuration file in clear text. This includes the client alias passwords and file access keys. This may or may not be acceptable. In cases where clear text is not acceptable, you should secure that data.

Sterling B2B Integrator includes a utility called zenginSecureConfig that obscures (encrypts) the client alias passwords and file access keys contained in the Zengin XML configuration file.

Specify the path to the Sterling B2B Integrator installation directory for install_dir and the Zengin XML configuration file name for configFileName. The [encoding] parameter allows you to enter an optional character encoding. If not entered, the utility uses the default value of UTF-8.

When the zenginSecureConfig utility is finished running, all client passwords and file access keys are secure and may be safely stored in the system.

After the secure values have been reset, run the zenginSecureConfig utility, if needed, to secure any new values.

Using the zenginConfigHelper Utility

To export a Zengin XML configuration from the data source to a file, use the zenginConfigHelper utility provided with Sterling B2B Integrator. This utility also allows you to import a Zengin XML Configuration file to the data source and can be used instead of the Zengin Configuration Import service for this purpose. The zenginConfigHelper utility is especially useful for easily importing configuration files created with the zenginSecureConfig utility.

Specify the path to the Sterling B2B Integrator installation directory for install_dir and the Zengin XML configuration file name for configFileName.

Configuring the Zengin TCP/IP Adapter

To configure the Zengin TCP/IP adapter, you must configure both the Zengin Sender and Requester adapter and the Zengin Receiver and Responder adapter by specifying field settings in Sterling B2B Integrator and in the Graphical Process Modeler. For general information about service and adapter configurations, see Creating a Service Configuration.

Configuring the Zengin Sender and Requester Adapter

Sterling B2B Integrator Configuration

You can create as many configurations of the Zengin Sender and Requester adapter as necessary. If you leave the optional parameters in the following table blank, you can use a single adapter instance for multiple remote Zengin servers.

The following table describes the fields used to configure the Zengin Sender and Requester adapter in Sterling B2B Integrator:

GPM Configuration

The following table describes the fields used to configure the Zengin Sender and Requester adapter in the GPM:

Configuring the Zengin Receiver and Responder Adapter

Sterling B2B Integrator Configuration

Due to TCP/IP requirements, only one configuration of the Zengin Receiver and Responder is allowed for a particular port. The following table describes the field used to configure the Zengin Receiver and Responder adapter in Sterling B2B Integrator:

GPM Configuration

There is no configuration required in the GPM for the Zengin Receiver and Responder adapter.

Configuring the zengin.properties File

The zengin.properties file in the properties directory provides settings that control the retry behavior of the Zengin TCP/IP adapter and how it handles files containing variable-length records.

Example Business Processes

Receive Example

This business process is called when a file is received and it saves the file to disk. Note that the Zengin TCP/IP adapter invokes the business process when a file is received, the business process does not invoke the adapter.

<process name="zengin_file_sys_write">
 <sequence name="Main Sequence">
    <operation name="File System Adapter">
      <participant name="my_file_sys"/>
      <output message="FileSystemInputMessage">
       <assign to="Action">FS_EXTRACT</assign>
       <assign to="assignedFilename">received_filename</assign>
       <assign to="extractionFolder">/my_directory</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="inmsg">
       <assign to="." from="*"></assign>
     </input>
    </operation>
 </sequence> 
</process>

Respond Example

This business process is called when the Zengin TCP/IP adapter receives and responds to a request to send a file. The business process reads a file from the disk to be sent back to the remote Zengin server. Note that the Zengin TCP/IP adapter invokes the business process when a request is received. The business process does not invoke the adapter.

<process name = "zengin_file_sys_read"> 
  <sequence name="Main Sequence">
   <operation name="File System Adapter">
      <participant name="my_file_sys"/>
     <output message="FileSystemInputMessage">
       <assign to="Action">FS_COLLECT</assign>
       <assign to="assignedFilename">respond_filename</assign>
       <assign to="collectionFolder">/my_directory</assign>
       <assign to="deleteAfterCollect">false</assign>
       <assign to="filter">respond_fixed_uncompr</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="inmsg">
       <assign to="." from="*"></assign>
     </input>
    </operation>
 </sequence> 
</process>

Send Example

This business process sends a single file to a remote Zengin server.

<process name = "zengin_sender"> 
 <sequence name="Main Sequence">
    
   <operation name="send fixed uncompr">
     <participant name="zengin_sender"/>
     <output message="output">
        <assign to="ZenginRemoteServerAlias">Ros3</assign>
       <assign to="ZenginFileAlias">send_fixed_uncompr</assign>
       <assign to="ZenginMode">send</assign>
       <assign to="ZenginHostname">123.45.67.8</assign>
       <assign to="ZenginPort">5020</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="input">
       <assign to="." from="*"></assign>
     </input>
    </operation>
   <operation name="send var uncompr">
     <participant name="zengin_sender"/>
     <output message="output">
        <assign to="ZenginRemoteServerAlias">Ros3</assign>
       <assign to="ZenginFileAlias">send_variable_uncompr</assign>
       <assign to="ZenginMode">send</assign>
       <assign to="ZenginHostname">123.45.67.8</assign>
       <assign to="ZenginPort">5020</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="input">
       <assign to="." from="*"></assign>
     </input>
    </operation>
   
  </sequence> 
</process>

Send Multiple Files Example

This business process sends several files to a remote Zengin server.

<process name = "zengin_send_mult"> 
 <sequence name="Main Sequence">
    
   <assign to="myDocs/send_fixed_uncompr" from="PrimaryDocument/@*" 
               append="true">
   </assign>
    <assign to="myDocs/send_variable_uncompr" from="PrimaryDocument/@*" 
       append="true"></assign>
   
    <operation name="call sender">
     <participant name="zengin_sender"/>
     <output message="output">
        <assign to="ZenginRemoteServerAlias">Ros3</assign>
       <assign to="ZenginDocuments">//myDocs/*</assign>
       <assign to="ZenginMode">send</assign>
       <assign to="ZenginHostname">123.45.67.8</assign>
       <assign to="ZenginPort">5020</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="input">
       <assign to="." from="*"></assign>
     </input>
    </operation>
 </sequence> 
</process>

Request Files Sample

This business process requests files from a remote Zengin server.

<process name = "zengin_requester"> 
  <sequence name="Main Sequence">
      <operation name="fixed uncompr">
      <participant name="zengin_sender"/>
      <output message="output">
       <assign to="ZenginRemoteServerAlias">Ros3</assign>
       <assign to="ZenginFileAlias">request_fixed_uncompr</assign>
       <assign to="ZenginMode">request</assign>
       <assign to="ZenginHostname">123.45.67.8</assign>
       <assign to="ZenginPort">5020</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="input">
       <assign to="." from="*"></assign>
     </input>
    </operation>
   <operation name="File System Adapter">
     <participant name="file_sys"/>
     <output message="FileSystemInputMessage">
       <assign to="Action">FS_EXTRACT</assign>
       <assign to="assignedFilename">request_fixed_uncompr</assign>
       <assign to="extractionFolder">/myDirectory</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="inmsg">
       <assign to="." from="*"></assign>
     </input>
    </operation>
   
    <operation name="variable uncompr">
     <participant name="zengin_sender"/>
     <output message="output">
        <assign to="ZenginRemoteServerAlias">Ros3</assign>
       <assign to="ZenginFileAlias">request_var_uncompr</assign>
       <assign to="ZenginMode">request</assign>
       <assign to="ZenginHostname">123.45.67.8</assign>
       <assign to="ZenginPort">5020</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="input">
       <assign to="." from="*"></assign>
     </input>
    </operation>
   <operation name="File System Adapter">
     <participant name="file_sys"/>
     <output message="FileSystemInputMessage">
       <assign to="Action">FS_EXTRACT</assign>
       <assign to="assignedFilename">request_var_uncompr</assign>
       <assign to="extractionFolder">/myDirectory</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="inmsg">
       <assign to="." from="*"></assign>
     </input>
    </operation>
   
    <operation name="fixed compr">
     <participant name="zengin_sender"/>
     <output message="output">
        <assign to="ZenginRemoteServerAlias">Ros3</assign>
       <assign to="ZenginFileAlias">request_fixed_compr</assign>
       <assign to="ZenginMode">request</assign>
       <assign to="ZenginHostname">123.45.67.8</assign>
       <assign to="ZenginPort">5020</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="input">
       <assign to="." from="*"></assign>
     </input>
    </operation>
   <operation name="File System Adapter">
         <participant name="file_sys"/>
         <output message="FileSystemInputMessage">
           <assign to="Action">FS_EXTRACT</assign>
           <assign to="assignedFilename">request_fixed_compr</assign>
           <assign to="extractionFolder">/myDirectory</assign>
           <assign to="." from="*"></assign>
         </output>
          <input message="inmsg">
           <assign to="." from="*"></assign>
         </input>
    </operation>
   
    <operation name="variable compr">
     <participant name="zengin_sender"/>
     <output message="output">
        <assign to="ZenginRemoteServerAlias">Ros3</assign>
       <assign to="ZenginFileAlias">request_var_compr</assign>
       <assign to="ZenginMode">request</assign>
       <assign to="ZenginHostname">123.45.67.8</assign>
       <assign to="ZenginPort">5020</assign>
       <assign to="." from="*"></assign>
     </output>
      <input message="input">
       <assign to="." from="*"></assign>
     </input>
    </operation>
   
    <operation name="File System Adapter">
         <participant name="file_sys"/>
         <output message="FileSystemInputMessage">
           <assign to="Action">FS_EXTRACT</assign>
           <assign to="assignedFilename">request_var_compr</assign>
           <assign to="extractionFolder">/myDirectory</assign>
           <assign to="." from="*"></assign>
         </output>
          <input message="inmsg">
           <assign to="." from="*"></assign>
         </input>
    </operation>
 </sequence> 
</process>