Merge pull request #12 from jananithangavel/DOC

add Documentation

README.md

@@ -1,11 +1,15 @@
-#ISO8583 ESB Connector
+# ISO8583 EI Connector
 
-ISO8583 connector allows you to send the ISO8583 standard messages through WSO2 ESB. ISO8583 is a message standard which is using in financial transactions.
-#Build
+ISO8583 connector allows you to send the ISO8583 standard messages through WSO2 EI. ISO8583 is a message standard which is using in financial transactions.
+
+**[ISO8583 EI Connector documentation v1.0.2](docs/README.md)**
+
+# Build
 
 mvn clean install
-#How You Can Contribute
+
+# How You Can Contribute
 
 You can create a third party connector and publish in WSO2 Connector Store.
 
-https://docs.wso2.com/display/ESBCONNECTORS/Creating+a+Third+Party+Connector+and+Publishing+in+WSO2+Connector+Store
+https://docs.wso2.com/display/ESBCONNECTORS/Creating+and+Publishing+a+Third+Party+Connector

docs/README.md

@@ -0,0 +1,14 @@
+# ISO8583 Connector
+
+The ISO8583 [Connector](https://docs.wso2.com/display/EI611/Working+with+Connectors) allows you to send ISO8583 standard messages through the ESB Profile of WSO2 Enterprise Integrator (WSO2 EI). ISO8583 is an international messaging standard for financial transaction card originated messages, and is commonly used in transactions between devices such as point-of-sale(POS) terminals and automated teller machines(ATMs).
+Although there are various versions of the ISO8583 standard, this connector is developed based on the 1987 version. For more information on the ISO8583 standard, see [ISO8583 Documentation](https://en.wikipedia.org/wiki/ISO_8583).
+
+## Getting started
+To get started, go to [Configuring the ISO8583 Connector](config.md). Once you have completed your configurations, you can work with ISO8583 standard messages through the ESB Profile of WSO2 EI.
+
+## Additional information
+For general information on using connectors and their operations in your configurations, see [working with Connectors](https://docs.wso2.com/display/EI611/Working+with+Connectors). To download the connector, go to [https://store.wso2.com/store/assets/esbconnector/details/iso8583](https://store.wso2.com/store/assets/esbconnector/details/e4cf3fd5-445f-4317-beb6-09998906fb0d), click ISO8583, and then click **Download Connector**. Next, you can [add and enable the connector](https://docs.wso2.com/display/EI611/Working+with+Connectors+via+the+Management+Console) in the ESB Profile of WSO2 EI.
+
+| | Version |
+| ------------- |-------------|
+| Connector    | 1.0.2 |

docs/config.md

@@ -0,0 +1,85 @@
+# Configuring the ISO8583 Connector
+
+To configure the ISO8583 connector, download the following .jar files from the given locations and copy the files to the <EI_HOME>/lib directory:
+
+* Download jpos-1.9.4.jar from [http://mvnrepository.com/artifact/org.jpos/jpos/1.9.4](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](http://mvnrepository.com/artifact/org.jdom/jdom/1.1.3).
+* Download commons-cli-1.3.1.jar from [http://mvnrepository.com/artifact/commons-cli/commons-cli/1.3.1](http://mvnrepository.com/artifact/commons-cli/commons-cli/1.3.1). 
+
+To use the ISO8583 connector, add the <iso8583.init> element in your configuration before carrying out any other operation.
+
+>> NOTE : For testing purposes, you need to have a test server (basically a java socket connection that listens on port 5010) to handle ISO8583 requests that come from the connector. You also need to generate responses by changing the relevant response fields, and then send the responses back to the connector.
+You can test the connector with the sample Java server program that is provided in the following git location: 
+https://github.com/wso2-docs/CONNECTORS/tree/master/ISO8583/ISO8583TestServer
+
+**init**
+```xml
+<iso8583.init>
+       <serverHost>localhost</serverHost>
+       <serverPort>5010</serverPort>
+</iso8583.init>
+```
+**Properties** 
+* serverHost: The host of the server.
+* serverPort: The port on which the server can start listening for messages.
+
+Now that you have connected to the ISO8583 connector, take a look at the information in the following sections to start working with ISO8583 messages using the connector.
+
+### Sending an ISO8583 message
+
+To send an ISO8583 message, you need to use the <iso8583.sendMessage/> operation in your configuration.
+You can use a REST client to send an XML message, set the Content-Type header in the REST client as application/xml, and then POST the body in XML format. 
+
+Messages that you send should be structured in the following XML format:
+
+```xml
+<ISOMessage>
+      <header>AAAAaw==</header>
+      <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>
+```
+>> NOTE: You can include required header information within the header tag in <ISOMessage>. It supports 2-byte or 4-byte headers. 
+To include header information, you need to convert the 2-byte or 4-byte header into a string using base64 encoding, and then specify the string value within the header tag.
+
+>> NOTE : If you use the sample Java server program at https://github.com/wso2-docs/CONNECTORS/tree/master/ISO8583/ISO8583TestServer to send an ISO8583 request with a header value from the connector, you need to update the iso87ascii.xml file with the relevant headerLength information.
+
+## Sample configuration
+
+Following is a sample proxy service that illustrates how to connect to a test server with the init operation, and then use the sendMessage operation. 
+
+**Sample Proxy**
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<proxy xmlns="http://ws.apache.org/ns/synapse"
+       name="ISO8583_Test"
+       transports="https,http"
+       statistics="disable"
+       trace="disable"
+       startOnLoad="true">
+   <target>
+      <inSequence>
+         <iso8583.init>
+            <serverHost>localhost</serverHost>
+            <serverPort>5010</serverPort>
+         </iso8583.init>
+         <iso8583.sendMessage/>
+         <respond/>
+      </inSequence>
+      <outSequence>
+         <log/>
+         <send/>
+      </outSequence>
+   </target>
+   <description/>
+</proxy>               
+```
+
+>> NOTE : The ISO8583 connector uses the jpos library, which is a third party library that provides a high-performance bridge between card messages generated at point of sale terminals, ATMs, and internal systems across the entire financial messaging network. The jposdef.xml file has the field definitions of standard ISO8583 messages. According to the field definitions, each ISO8583 message in XML format coming from the REST client is packed and sent to the test server.