Tuesday, September 13, 2016

ISO8583 [Inbound + Connector] Scenarios

In this blog, we will see how can we use both inbound and connector for different kind of scenarios. 
Check previous post for basic use-case of [ISO8583 Inbound + Connector]

First scenario satisfies the following flow.



  • Client send ISO8583 String messages to the inbound.
  • Inbound will consume the messages and inject it into the sequence in xml format.
  • Now Xml format ISO8583 Messages will be in the message context.
  • Instead of using Rest Client, Connector will get the message from the message context, then packed the fields to form ISO8583 String according to the field definitions and send it to the server.
  • Server will acknowledge the connector by changing the relevant response fields and response will be set into message context in xml format, Inbound get the response and packed the response again and acknowledge the client with the response.
In order to check with this scenario, you need to get the inbound org.wso2.carbon.inbound.iso8583-1.0.0.jar (click Download Streaming Connector), get the connector zip (click Download Connector) from the https://store.wso2.com/store/assets/esbconnector/ISO8583 or by building the source code (connector - https://github.com/wso2-extensions/esb-connector-iso8583/tree/org.wso2.carbon.connector.ISO8583-1.0.0 , inbound - https://github.com/wso2-extensions/esb-inbound-iso8583/tree/org.wso2.carbon.inbound.iso8583-1.0.0 ),  download the jpos-1.9.4.jar from the http://mvnrepository.com/artifact/org.jpos/jpos/1.9.4 , download jdom-1.1.3.jar from http://mvnrepository.com/artifact/org.jdom/jdom/1.1.3 and download commons-cli-1.3.1.jar from http://mvnrepository.com/artifact/commons-cli/commons-cli/1.3.1 . Then copy the jars to the <ESB_HOME>/repository/components/lib directory and copy the  jposdef.xml file into <ESB_HOME>. Do the Connector configurations and with ESB by following Using a Connector. The recommend ESB version is 4.9 and later .

Note :  Here the ISO8583 inbound will listening on port 5000, so client will connected to that port
            ISO8583 connector will connect with port 5010, and the server will listen on port 5010.
 
Sample Configuration 

Within the request sequence tag add the <ISO8583.init> element in your configuration and use </ISO8583.sendMessage> operation to send the message.

 <sequence name="request" onError="fault">
        <property expression="$body" name="body"/>
        <ISO8583.init>
            <serverHost>localhost</serverHost>
            <serverPort>5010</serverPort>
        </ISO8583.init>
        <ISO8583.sendMessage>
            <body>request</body>
        </ISO8583.sendMessage>
        <log level="full"/>
    </sequence> 


Then update the inbound endpoint as follows.

<inboundEndpoint
        class="org.wso2.carbon.inbound.iso8583.listening.ISO8583MessageConsumer"
        name="custom_listener" onError="fault" sequence="request" suspend="false">
        <parameters>
            <parameter name="sequential">true</parameter>
            <parameter name="inbound.behavior">listening</parameter>
            <parameter name="port">5000</parameter>
        </parameters>
  </inboundEndpoint> 



If you have successfully configured with this  ISO8583[Inbound + Connector], then you can see the following log in your console.

Inbound will consume the message which is send by the client 

INFO - LogMediator To: , MessageID: urn:uuid:6C838679BEE7DB646A1473682524513, Direction: request, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"><soapenv:Body><ISOMessage><data><field id="0">0200</field><field id="3">568893</field><field id="4">000000020000</field><field id="7">0110563280</field><field id="11">456893</field><field id="44">DFGHT</field><field id="105">ABCDEFGHIJ 9871236548</field></data></ISOMessage> 

Connector get these fields from message context  and packed the message and send it to server . Server will acknowledge the connector with the string of IS08583 Message. The response will set into the message context as following and client will acknowledge via inbound with the same string of ISO8583 Messages.

<ISOMessage><data><field id="0">0210</field><field id="3">568893</field><field id="4">000000020000</field><field id="7">0110563280</field><field id="11">456893</field><field id="39">00</field><field id="44">DFGHT</field><field id="105">ABCDEFGHIJ 9871236548</field></data></ISOMessage></soapenv:Body></soapenv:Envelope>

In the second scenario, you can consider ISO8583 Inbound as a server and ISO8583 Connector as a client .
So, Here Connector (Client) will send String of ISO8583 Messages to Inbound (Server) and Inbound (Server) acknowledge the Connector (Client). 
  1. You can use Rest-Client to initiate the ISO8583 Messages in xml format.
  2. Then the connector will get the fields and packed as String of ISO8583 Message.
  3. Packed message will be sent to the Inbound (Since it is listen on same port).
  4. Inbound consume the String Message and inject the message into sequence in xml format and then acknowledge the connector with the string of ISO8583 Message by changing  relevant response fields.
  5. Acknowledgment will set into message context in xml format.    
 
Sample Configuration 
Since we consider the inbound as a server and connector as a client, we have to maintain the same port for inbound and connector configuration.
In order to check with this scenario, you have to do some minor changes in Inbound and its configuration as following. 
  <proxy name="ISO8583_Test" startOnLoad="true" trace="disable" transports="https http">
        <description/>
        <target>
            <inSequence>
                <ISO8583.init>
                    <serverHost>localhost</serverHost>
                    <serverPort>5000</serverPort>
                </ISO8583.init>
                <ISO8583.sendMessage/>
                <log level="full"/>
                <respond/>
            </inSequence>
            <outSequence>
                <log/>
                <send/>
            </outSequence>
        </target>
    </proxy>


 <sequence name="request" onError="fault">
        <log level="full"/>
    </sequence>


<inboundEndpoint
        class="org.wso2.carbon.inbound.iso8583.listening.ISO8583MessageConsumer"
        name="custom_listener" onError="fault" sequence="request" suspend="false">
        <parameters>
            <parameter name="sequential">true</parameter>
            <parameter name="inbound.behavior">listening</parameter>
            <parameter name="port">5000</parameter>
        </parameters>

</inboundEndpoint> 


  • Now, You have made the configuration,  In Rest-client set the header application/xml as Content-Type. POST the body in xml format and xml format message should be in the following structure.
 <ISOMessage>
      <data>
        <field id="0">0200</field>
        <field id="3">568893</field>
        <field id="4">000000020000</field>
        <field id="7">0110563280</field>
        <field id="11">456893</field>
        <field id="44">DFGHT</field>
        <field id="105">ABCDEFGHIJ 9871236548</field>
      </data>
</ISOMessage>


If all the  configurations are correct, then you can see the following log in your console.

Inbound will inject message into sequence

INFO - LogMediator To: , MessageID: urn:uuid:99A310AC504D6230D81473787521614, Direction: request, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"><soapenv:Body><ISOMessage><data><field id="0">0200</field><field id="3">568893</field><field id="4">000000020000</field><field id="7">0110563280</field><field id="11">456893</field><field id="44">DFGHT</field><field id="105">ABCDEFGHIJ 9871236548</field></data></ISOMessage></soapenv:Body></soapenv:Envelope> 

Connector get acknowledgement and the response message will set in message context as following

<ISOMessage><data><field id="0">0210</field><field id="3">568893</field><field id="4">000000020000</field><field id="7">0110563280</field><field id="11">456893</field><field id="39">00</field><field id="44">DFGHT</field><field id="105">ABCDEFGHIJ 9871236548</field></data></ISOMessage>

WSO2 ESB Inbound and connector for ISO8583

ISO8583 is a STANDARD message format used for credit card transactions, banking and other commercial interaction between different systems.

The main format of the ISO8583 is something like this:
  ISO header (optional)|Message Type|primary bitmap|secondary bitmap (optional)|data fields
The ISO header - is a string containing some code that can vary according to the message type.
The message type - is a number expressed as 4 hex digits (or 2 bytes when using binary format).
The bitmap - is 64 bits long and it is encoded as 16 hex characters or as 8 bytes when using binary format. Every bit that is set in the bitmap indicates that the corresponding field is present. If the first bit is set, then field 1 is present, and so on.

For more information about ISO8583, refer the following link
http://jimmod.com/blog/2011/07/25/jimmys-blog-iso-8583-introduction-beginners-tutorial/

ISO8583 [Inbound+connector] development based on following use-case
















The ISO8583 inbound endpoint [1] allows you to consume the ISO8583 standard message which is sent by simple java client [2], and then convert it into xml format by using the message builder to access the ISO8583 messages through WSO2 ESB. Since it is listening inbound, it is listening on port 5000. When the client is connected on port 5000 , ISO8583 inbound starts to consume the ISO8583 standard messages and ISO8583 Messages are inject into the sequence in following XML format.
 
<ISOMessage>
      <data>
        <field id="0">0200</field>
        <field id="3">568893</field>
        <field id="4">000000020000</field>
        <field id="7">0110563280</field>
        <field id="11">456893</field>
        <field id="44">DFGHT</field>
        <field id="105">ABCDEFGHIJ 9871236548</field>
      </data>
</ISOMessage>

 
In order to use the ISO8583 inbound endpoint, you need to download the inbound org.wso2.carbon.inbound.iso8583-1.0.0.jar from the https://store.wso2.com/store/assets/esbconnector/ISO8583 or by building the source code https://github.com/wso2-extensions/esb-inbound-iso8583/tree/org.wso2.carbon.inbound.iso8583-1.0.0 ) download the jpos-1.9.4.jar from the http://mvnrepository.com/artifact/org.jpos/jpos/1.9.4 , download jdom-1.1.3.jar from http://mvnrepository.com/artifact/org.jdom/jdom/1.1.3 and download commons-cli-1.3.1.jar from http://mvnrepository.com/artifact/commons-cli/commons-cli/1.3.1 . Then copy the jars to the <ESB_HOME>/repository/components/lib directory. The recommend ESB version is 4.9 and later . 

Sample Inbound Configuration
Login with ESB Management console , go to Main --> Home --> Manage --> Service Bus --> Inbound Endpoints and add new endpoint (E.g custom_listener), then update the Inbound Endpoint as in the following UI . Here the Port is the main  parameter and the client need to connect with inbound by using the port.












Or you can directly update the following inbound endpoint and  request sequence (ISO8583 Messages will inject into this sequence) in Home -- > Manage -- > Service Bus -- > Source View

<inboundEndpoint
        class="org.wso2.carbon.inbound.iso8583.listening.ISO8583MessageConsumer"
        name="iso8583" onError="fault" sequence="request" suspend="false">
        <parameters>
            <parameter name="inbound.behavior">listening</parameter>
            <parameter name="sequential">true</parameter>
            <parameter name="port">5000</parameter>
        </parameters>
</inboundEndpoint>

 <sequence name="request" onError="fault">
        <log level="full"/>
    </sequence>

  
 Now you are configured with the inbound and you can test with the inbound. Following is the sample message [a] which is send by simple java-client and the inbound consumes [b] the incoming ISO8583 Message into the sequence, then acknowledge [c] the client by changing the relevant response fields according to the limitations See the link .

[a] 0200B220000100100000000000000002000020134500000050000001115221801234890610000914XYRTUI5269TYUI021ABCDEFGHIJ 1234567890

[b]  
INFO - LogMediator To: , MessageID: urn:uuid:F4963E16A27CD0AC2A1473584339729, Direction: request, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope"><soapenv:Body><ISOMessage><data><field id="0">0200</field><field id="3">201345</field><field id="4">000000500000</field><field id="7">0111522180</field><field id="11">123489</field><field id="32">100009</field><field id="44">XYRTUI5269TYUI</field><field id="111">ABCDEFGHIJ 1234567890</field></data></ISOMessage></soapenv:Body></soapenv:Envelope>

[c] 0210B22000010210000000000000000200002013450000005000000111522180123489061000090014XYRTUI5269TYUI021ABCDEFGHIJ 1234567890

Note : ISO8583 Inbound acts as a server , Thread pool is used to handle concurrent messages with the inbound. The number of threads in the pool is determined by these variables:
  • corePoolSize           : The number of threads to keep in the pool , even if they are idle.
  • maximumPoolSize  : The maximum number of threads to allow in the pool.
Another parameter in threadPool configuration is keepAliveTime, Which is the maximum time that excess idle threads will be alive for new tasks before terminating.
The above parameters are optional one . If you need to change the values of these parameters (or let it with the default value), then you can add those parameters in your inbound configuration as below 
<inboundEndpoint
        class="org.wso2.carbon.inbound.iso8583.listening.ISO8583MessageConsumer"
        name="custom_listener" onError="fault" sequence="request" suspend="false">
        <parameters>
            <parameter name="keepAlive">1</parameter>
            <parameter name="maxThreads">2</parameter>
            <parameter name="coreThreads">1</parameter>
            <parameter name="sequential">true</parameter>
            <parameter name="queueLength">1</parameter>
            <parameter name="inbound.behavior">listening</parameter>
            <parameter name="port">5000</parameter>
        </parameters>
    </inboundEndpoint>

 
In following blog you can see, how the connector works with ESB.
References 
https://docs.wso2.com/display/ESB490/Custom+Inbound+Endpoint 
https://docs.wso2.com/display/ESBCONNECTORS/Configuring+ISO8583+Inbound+Operations 
https://github.com/wso2/carbon-mediation/tree/master/components/inbound-endpoints 
https://en.wikipedia.org/wiki/ISO_8583
http://jimmod.com/blog/2011/07/26/jimmys-blog-iso-8583-tutorial-build-and-parse-iso-message-using-jpos-library/ 
https://docs.oracle.com/javase/tutorial/essential/concurrency/pools.html 
http://www.javatpoint.com/java-thread-pool 

ISO8583 Connector (WSO2)

We will see on this blog, how the ISO8583 connector works with WSO2 ESB. Based on the previous article, Inbound acts as a consumer and now the connector acts as a producer.

ISO8583 connector [1] allows you to send (produce) the ISO8583 standard messages through WSO2 ESB. There are various versions in ISO8583 standard, Here the connector is developed based on 1987 version and used jpos which is the third party library , and jposdef.xml has the field definitions of the standard ISO8583 Messages. According to the field definitions each and every ISO8583 Messages in xml format which comes from the Rest-client, will be packed and will be send to the Test-server [2]. The Test-server need to be listen on port 5010,  consume the String of ISO8583 Messages and acknowledge the connector by changing the relevant response fields according to the requirements and the response ISO8583 Messages will be set into the message context in xml format.

Sample ISO8583 Connector Configuration
In order to use the ISO8583 connector, you need to download the jpos-1.9.4.jar from the http://mvnrepository.com/artifact/org.jpos/jpos/1.9.4 , download jdom-1.1.3.jar from http://mvnrepository.com/artifact/org.jdom/jdom/1.1.3 and download commons-cli-1.3.1.jar from http://mvnrepository.com/artifact/commons-cli/commons-cli/1.3. Then copy the jars to the <ESB_HOME>/repository/components/lib directory and copy the jposdef.xml file into <ESB_HOME>. The recommend ESB version is 4.9 and later .For general information on using connectors and their operations in your ESB configurations, see Using a Connector.

To use the ISO8583 connector, add the <ISO8583.init> element in your configuration before connecting with Test-server. Here the host and port are the main parameters to connect with Test-server

<ISO8583.init>
       <serverHost>localhost</serverHost>
       <serverPort>5010</serverPort>
</ISO8583.init>

To send the messages, use </ISO8583.sendMessage> operation and using Rest-client to send the xml format messages. In Rest-client set the header application/xml as Content-Type.
POST the body in xml format and xml format message should be in the following structure. 

<ISOMessage>
      <data>
        <field id="0">0200</field>
        <field id="3">568893</field>
        <field id="4">000000020000</field>
        <field id="7">0110563280</field>
        <field id="11">456893</field>
        <field id="44">DFGHT</field>
        <field id="105">ABCDEFGHIJ 9871236548</field>
      </data>
</ISOMessage>



If you have done the configuration correctly with ISO8583 Connector, then you can see the log in your console.

INFO - LogMediator To: /services/ISO8583_Test, MessageID: urn:uuid:7cf953fa-8d29-4054-a144-9a44286a3bdb, Direction: request, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelop/"><soapenv:Body><ISOMessage>
      <data>
        <field id="0">0200</field>
        <field id="3">568893</field>
        <field id="4">000000020000</field>
        <field id="7">0110563280</field>
        <field id="11">456893</field>
        <field id="44">DFGHT</field>
        <field id="105">ABCDEFGHIJ 9871236548</field>
      </data>
</ISOMessage>


In your Test-server you can see the String ISO8583 Messages (Packed Message).

0200B2200000001000000000000000800000568893000000020000011056328045689305DFGHT021ABCDEFGHIJ 9871236548

Now the Test-server acknowledge the connector, the response messages will be set into the message context as following. 

<ISOMessage><data><field id="0">0210</field><field id="3">568893</field><field id="4">000000020000</field><field id="7">0110563280</field><field id="11">456893</field><field id="39">00</field><field id="44">DFGHT</field><field id="105">ABCDEFGHIJ 9871236548</field></data></ISOMessage></soapenv:Body></soapenv:Envelope>

Note : If you need to see the above log in your ESB console, then you have to put the following in your configuration.
<log level="full"/> 

In following post, we will see different kind of scenarios with WSO2 ESB ISO8583 Inbound and Connector.
  
References
https://docs.wso2.com/display/ESBCONNECTORS/Configuring+ISO8583+Connector+Operation 
http://www.iso.org/iso/home.html 
https://en.wikipedia.org/wiki/ISO_8583 
http://www.codeproject.com/Articles/100084/Introduction-to-ISO-8583 
https://docs.wso2.com/display/ESBCONNECTORS/Writing+a+Connector 
 https://milindaperera.blogspot.com/2014/10/create-wso2-esb-connector-for-absolute.html
http://chanakaindrajith.blogspot.com/2014/04/getting-started-with-wso2-esb-connectors.html