Build a RESTful API for IFS with WSO2 and knak.it connector

I have tried several different integration tools like Mulesoft, Azure Service Bus and and some native coding with IFS but nothing worked as good (and free) as WSO2 Enterprise Integrator so far. It’s a complete Integration tool kit with tons of features so you can basically integrate IFS with anything with right combination of configuration and most possibly ZERO lines of coding!

There are many integration possibilities for IFS with the combination of WSO2 and currently I’m working on integrating a Chatbot to interact with IFS and some IOT stuff and will be posting more on these later.

Most of the modern day applications expose a JSON API so I thought it would be good idea to start with a JSON API so same concept can be used for other examples.

In this example…

In this example, we create RESTful API which has 3 query parameters (Company, Site,Order No) and return corresponding record from IFS customer order using a select statement

Input request:

http://wso2_base_url:8280/ifsroot/getOrder?company=10&contract=1&order_no=BP10111

Output:

 {
    "company": 10,
    "contract": 1,
    "order_no": "BP10111",
    "order_code": "O",
    "customer_no": "BP10",
    "date_entered": "Wed Apr 18 20:55:24 CEST 2001",
    "wanted_date": "Fri Apr 20 00:00:00 CEST 2001",
    "state": "Invoiced/Closed"
}

First Steps…

Step 1 – Create ESB Solution project

• Open WSO2 Integration Studio
• File, New, ESB Solution Project
• Make sure all three project types are checked

Step 2 – Add IFS connector to the project

• Download knak.it connector .zip https://github.com/knakit/wso2-esb-connector-ifs/files/3485001/knakitifs-connector-1.0.0.zip
• RMB on ESB project > Add or Remove Connector > Add Connector > Add from File System.
• Locate downloaded .zip file and add
• RMB on Connector Exporter Project, New, Add or remove connector
• Add the knak.it connector

Step 3 – Create REST API project

Create a new REST API by RMB on ESB solution project node or src/main/synapse-config/api

Make sure to give meaningful Context name. This will be the root of the REST API URL

Eg: http://[wso2_base_url]:8280/root/...

Step 4 – Create new API Resource

Drag and drop APIResource item from the pallet to the API design worksheet

• URL Style: URI_TEMPLATE
• URI Template: /getOrder

Eg:  http://[wso2_base_url]:8280/root/getOrder/...

• Protocols: http, https
• Methods : Get (in this example we fetch a result of SQL query so GET is sufficient)

Step 5 – Add Properties to read query parameters

Our API accepts Company, Site and Order No as inline query parameters. we need to define Properties to read these parameters.

Drag and drop 3 property items from pallet and define as below

• Value type: Expression
• Value Expression: company – $url:company site- $url:contract order no $url:order_no

design view looks like below after adding the parameters

Step 6 – Log property values (optional)

Add a log property to log the input values. This is an optional step.

Step 7 – Create IFS XML

Now we need to call IFS and retrieve the record with knak.it connector. For this we use SQL statement operation in knak.it connector.

XML format for SQL statement can be found in knak.it connector documentation

https://github.com/knakit/wso2-esb-connector-ifs/blob/master/doc/config.md#execute-sql-statement-and-retrieve-records-from-ifs

Drag and drop PayloadFactory mediator item from pallet and configure as below

Payload XML

<request>
	<bindVariables>
		<company>$1</company>
		<contract>$2</contract>
		<order_no>$3</order_no>
	</bindVariables>
	<sqlStatement>
select company, contract, order_no, order_code, customer_no, date_entered, wanted_delivery_date, state 
   from ifsapp.customer_order
   where company = :company
   and contract = :contract
   and order_no = :order_no
	</sqlStatement>
</request>

Here we execute following SQL in IFS to get the Customer Order record.

select company, contract, order_no, order_code, customer_no, date_entered, wanted_delivery_date, state 
   from ifsapp.customer_order
   where company = :company
   and contract = :contract
   and order_no = :order_no

Add 3 arguments of type Expression for each input parameter

Step 8 – Connect to IFS using knak.it connector

Next step is to execute the select statement in IFS and get the result. For this we use knak.it operation Select Statement. Drag and drop SelectStatement operation from pallet and configure as below.

Step 9 – Convert IFS response to JSON

SQL Result from knak.it connector is in XML format. WSO2 facilitates comprehensive data mapping tool which can be used to convert the IFS response into our preferable JSON format

knak.it Select Statement response

<ifs:resultSet xmlns:ifs="http://wso2.org/knak/ifs/connector">
    <ifs:record>
        <ifs:COMPANY ifs:Type="Text">10</ifs:COMPANY>
        <ifs:CONTRACT ifs:Type="Text">1</ifs:CONTRACT>
        <ifs:ORDER_NO ifs:Type="Text">BP10111</ifs:ORDER_NO>
        <ifs:ORDER_CODE ifs:Type="Text">O</ifs:ORDER_CODE>
        <ifs:CUSTOMER_NO ifs:Type="Text">BP10</ifs:CUSTOMER_NO>
        <ifs:DATE_ENTERED ifs:Type="Timestamp">Wed Apr 18 20:55:24 CEST 2001</ifs:DATE_ENTERED>
        <ifs:WANTED_DELIVERY_DATE ifs:Type="Timestamp">Fri Apr 20 00:00:00 CEST 2001</ifs:WANTED_DELIVERY_DATE>
        <ifs:STATE ifs:Type="Text">Invoiced/Closed</ifs:STATE>
    </ifs:record>
</ifs:resultSet>

JSON output

{
	"company": "10",
	"contract": "1",
	"order_no": "BP10111",
	"order_code": "O",
	"customer_no": "BP10",
	"date_entered": "Wed Apr 18 20:55:24 CEST 2001",
	"wanted_date": "Fri Apr 20 00:00:00 CEST 2001",
	"state": "Invoiced/Closed"
}

Drag and drop Data Mapper mediator from pallet and save it in the registry resource project created in step 1. Input and output of the data mapper can be configured visually in the designer

Change the DataMapper property Output Type to JSON

Step 10 – Return response to client

Add a Respond mediator to terminate the execution and return the response to the client

That’s basically the steps we’ll need to create the REST API. Now we are all set to test and deploy.

Test…

RMB on Composite Application project, Export Project Artifacts and Run.

Select all 3 projects created in Step 1

This will start the micro integrator embedded in WSO2 Integration Studio. It will start HTTP listener with port 8090. It’s time to test 🙂 I used Postman to call the REST API

Console output will show the input parameters and SQL statement extracted from the payload as below

Export and deploy in WSO2 ESB

Now we are all set to deploy the API in WSO2. RMB on Composite Application project, Export Composite Application Project. Choose a destination and select all 3 projects created in step 1 to be export. This will create .car file which can deploy in WSO2 as a Carbon Application

Resources

Source code for this example

knak.it IFS-WSO2 connector

WSO2 Enterprise Integrator

WSO2 Integration Studio

Update

This blog post was written based on the knak.it connector version 1.0. There are some improvements from version 1.1 onwards where it has a init operator where you can specify the login details separately. With the latest release, you can add the init operator before Step 8 and add the IFS URL and credentials instead of adding it in each operator.

Call sequence with the init operator looks like below.