WSO2 EI Introduction

Here is step by step guide how to install WSO2 EI and create Hello World like service.

Introduction

WSO2 Enterprise Integration (EI) is composite integration product that contains following components (please see http://wso2.com/integration/ for more information):

WSO2 Enterprise Service Bus (WSO2 ESB) - predecessor of WSO2 EI
WSO2 Message Broker (WSO2 MB)
WSO2 Data Services Server
WSO2 Business Process Server

WSO2 ESB itself is based on Apache Synapse (see http://synapse.apache.org/) and it uses WSO2 Carbon (OSGi based application server) as container. Please see http://wso2.com/products/carbon/ for more information about WSO2 Carbon.

One good reason to use WSO2 EI (instead of Apache Synapse) is nice Eclipse based IDE for development (called "Tooling" on http://wso2.com/integration#download page).

Requirements

Tested Environment is:

OS: Windows 7 Professional SP1, 64-bit
1xCPU
2GB RAM
30GB disk
KVM-QEMU Hypervisor (please see Install Windows7 on KVM Qemu for more information).

Installation

Installing Oracle JDK

Please download Oracle JDK 1.8 (JDK 8 is required for WSO2 EI 6.1.1) from http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html as Windows x64 item. Note: Version 8u144 (jdk-8u144-windows-x64.exe) was used.
Run downloaded exe (in this case jdk-8u144-windows-x64.exe)
Ensure that you have checked ON:
- Development Tools
You may UNcheck both:
- Source Code
- Public JRE
They are not needed for WSO2 EI and especially Public JRE is quite obtrusive.
After install please note your JDK location, typically it is something like: c:\Program Files\Java\jdk1.8.0_144

Installing WSO2 EI

Download/install:

Please go to http://wso2.com/integration#download to download WSO2 EI
- Fill in valid e-mail address
- click on Download Server
- you should be redirected to download like https://product-dist.wso2.com/products/enterprise-integrator/6.1.1/wso2ei-6.1.1.zip
Save wso2ei-6.1.1.zip somewhere

Extract ZIP:

To extract ZIP right-click on downloaded wso2ei-6.1.1.zip and select Extract all...
Change extraction path to something meaningful, for example: c:\WSO2\wso2ei-6.1.1
And click on Extract button.
After a while there should be extracted WSO2 EI server at c:\WSO2\wso2ei-6.1.1

WARNING: Windows ZIP Extraction is terribly slow (it showed scary 17minut estimated remaining time for me!!!). Use something more reliable if possible - for example favorite Total Commander

Testing standalone WSO2 EI server:

Add to beginning of c:\WSO2\wso2ei-6.1.1\bin\integrator.bat line setting JAVA_HOME:

@echo off
rem Remember to change the path is you installed different JDK or in different target...
set JAVA_HOME=c:\Program Files\Java\jdk1.8.0_144

run c:\WSO2\wso2ei-6.1.1\bin\integrator.bat in CMD Window

wait until this message appear in CMD (meaning that WSO2 EI is ready):

c:\WSO2\wso2ei-6.1.1\bin>integrator.bat
JAVA_HOME environment variable is set to c:\Program Files\Java\jdk1.8.0_144
CARBON_HOME environment variable is set to c:\WSO2\WSO2EI~1.1\bin\..
...
[...] []  INFO - StartupFinalizerServiceComponent WSO2 Carbon started in 385 sec
[...] []  INFO - CarbonUIServiceComponent Mgt Console URL  : https://192.168.122.143:9443/carbon/

Confirm Allow Access when Windows Firewall dialog appears.

Then open URL displayed on console (in my example https://192.168.122.143:9443/carbon/)

NOTE: it seems that current Carbon Application server contains expired certificate - please see https://github.com/wso2/carbon-kernel/issues/1442 Temporary solution: Just accept it...
Use login/password: admin/admin to login to Carbon Console
Click on Services -> List
Click on Try this Service link of service Version
Click on Try on alternate http (this is needed because https may not work due invalid server certificate)
Click on Send

You should see in Response panel XML response like:

<ns:getVersionResponse xmlns:ns="http://version.services.core.carbon.wso2.org">
   <return>WSO2 Enterprise Integrator-6.1.1</return>
</ns:getVersionResponse>

When done - hit Ctrl-C in your Carbon CMD Window
After a while confirm Terminate batch job (Y/N)? answering Y

Note: we terminated this Carbon instance to avoid later conflict with another instance run directly from Eclipse Tooling

Installing Eclipse Tooling for EI

Downloading Eclipse Tooling:

Go to http://wso2.com/integration#download page again
Fill-in you e-mail address again (if empty - depends on your cookies policy)
Click on link Download Tooling -> for Windows 64-bit
You should be redirected to download https://product-dist.wso2.com/products/enterprise-integrator/6.1.1/developer-studio-ei-eclipse-jee-mars-2-win64-x86_64-1.1.0.zip

Unpacking Eclipse:

Unpack downloaded developer-studio-ei-eclipse-jee-mars-2-win64-x86_64-1.1.0.zip into C:\WSO2 directory - it should create eclipse subfolder (to unzip file use same procedure as for wso2ei-6.1.1.zip)

Adding path to javaw.exe:

Right-click on c:\WSO2\eclipse\eclipse.ini
Select Open With -> Wordpad (Note: Do NOT use Notepad - it is unable to format Unix LF well)

Add these two lines just before -vmargs line:

-vm
c:\Program Files\Java\jdk1.8.0_144\bin\javaw.exe

Save/Close eclipse.ini in WordPad.

Now you can run c:\WSO2\eclipse\eclipse.exe

Confirm offered workspace (something like C:\Users\YOUR_LOGIN\workspace)
Now you should be ready to proceed to next chapter

Creating Hello World like service

Here we will create very simple REST-like service with one msg argument which would send back response like Hello, {msg}!.

Note: This part of tutorial is partially modeled by https://docs.wso2.com/display/EI600/Sending+a+Simple+Message. However we don't rely on invoking other service (we make our own payload).

Step-by-step guide how to create service:

Opening Eclipse:

Open your Eclipse tooling (if not running from previous chapter) by double-clicking on c:\WSO2\eclipse\eclipse.exe
Confirm selected workspace if needed
Close Welcome Window

Creating HelloService projects:

In menu select Developer Studio -> Open Dashboard
Click on ESB Solution Project (it should be the 1st row of the 2nd column)
Fill in HelloService to ESB Project Name:
Keep also checked and generated names for all 3 projects:
- Create Registry Resources Project (HelloServiceRegistry)
- Create Connector Exporter Project (HelloServiceConnectorExporter)
- Create Composite Application Project (HelloServiceCompositeApplication)
Click on Finish

Creating API:

API is Entry point to your new service
select Developer Studio Dashboard (this tab should be already there)
click on REST API
Wizard New Synapse API should appear
Keep selected Create a New API Artifact
Click on Next
Fill in:
- Name: HelloAPI
- Context: /hello
Click on Finish

Editing API parameters:

Now you should see active tab HelloAPI.xml in Design mode
Click on green box Resource
Activate Properties tab in bottom Windows
Change:
- URL Style to URI_TEMPLATE
- focus another entry (for example Protocol)
- now click on URI-Template and fill in: /{msg}
- again focus something elese (for example Protocol)
- Rather Save-all files using Ctrl-Shift-S

Now we have reeady API with context like /hello/Clever%20Boys - but it does not return response data yet.

To create response:

click back to your tab HelloAPI.xml
in Palette expand Mediators and select PayloadFactory
Drag and drop PayloadFactory at at the right of right Arrow from API Resource greenbox
Name it XML Response
Go to Properties tab and fill in:
- Payload: change <inline/> to:
```
<msg>Hello, $1!</msg>
```
- Args: click on Add
  - Change Type to Expression
  - Change Value to get-property('var.uri.msg')
Go back to Design
In palette expand again Mediators

Transporting message from Inboud to Outbound:

Drag-and-Drop Loopback right after our existing XML Response PayloadFactory

Sending back our XML response:

Drag-and-drop Send anywhere to Outbound flow (there are <- left arrows on this area)

To verify your source:

activate Source tab of ``HelloAPI.xml`
It should look like:

<?xml version="1.0" encoding="UTF-8"?>
<api context="/hello" name="HelloAPI" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="GET" uri-template="/{msg}">
        <inSequence>
            <payloadFactory description="XML Response" media-type="xml">
                <format>
                    <msg xmlns="">Hello, $1!</msg>
                </format>
                <args>
                    <arg evaluator="xml" expression="get-property('uri.var.msg')"/>
                </args>
            </payloadFactory>
            <loopback description="Loopback"/>
        </inSequence>
        <outSequence>
            <send/>
        </outSequence>
        <faultSequence/>
    </resource>
</api>

Activate again Developer Studio Dashboard tab
Click on Add Server -> Server link
Expand/Select: WSO2 -> WSO2 Enterprise Integrator 6.1.0
click on Next
change CARBON_HOME to C:/WSO2/wso2ei-6.1.1 (it should also clear STOP red mark)
click on Next
clikc on Next
on Add and Remove add your HelloServiceCompositeApplication to right list (select it and click on Add > button)
click on Finish

Start Carbon Server:

click on bottom window tab Servers
There should be (after a while) WSO2 Enterprise Integrator 6.1.0 at localhost [Stopped]
Right-click on it and select Start

Confirm Allow Access on Windows Firewall Dialog
Wait until new Browser window appear with Login to Carbon console
Also the Server state on Servers tab should change to [Started,Synchronized]

Fixing error:

[...] [EI-Core]  WARN - ApplicationManager No artifacts found to be deployed in this server. Ignoring Carbon Application : HelloServiceCompositeApplication_1.0.0.car

Using following:

Expand HelloServiceCompositeApplication and open its pom.xml (using double-click)
In Dependencies Check-ON HelloService (it is unchecked which is error!)
use Ctrl-S to Save
Now you should see in Console tab messages like:

[...] [EI-Core]  INFO - ApplicationManager Deploying Carbon Application : HelloServiceCompositeApplication_1.0.0.car...
[...] [EI-Core]  INFO - API Initializing API: HelloAPI
[...] [EI-Core]  INFO - DependencyTracker API : HelloAPI was added to the Synapse configuration successfully - [ Deployed From Artifact Container: HelloServiceCompositeApplication ] 
[...] [EI-Core]  INFO - APIDeployer API named 'HelloAPI' has been deployed from file : C:\WSO2\wso2ei-6.1.1\tmp\carbonapps\-1234\1504023457577HelloServiceCompositeApplication_1.0.0.car\HelloAPI_1.0.0\HelloAPI-1.0.0.xml
[...] [EI-Core]  INFO - ApplicationManager Successfully Deployed Carbon Application : HelloServiceCompositeApplication_1.0.0 {super-tenant}

Testing our new `HelloAPI`

For impatient:

Open this URL: http://localhost:8280/hello/Boys in your browser
Save result as xml, for example Boys.xml
Open it in your favorite application - even Notepad would suffice

Testing in Carbon console:

Login to Carbon console (there should be already browser window) using login/password: admin/admin
Click on Service Bus -> APIs
Copy&Paste API Invocation URL
Change that URL to something like may looks like http://localhost:8280/hello/Clever%20Boys
Try it in your browser (Save as XML file and look into it)

Installing curl

For future testing/diagnostics it is really good idea to have curl installed

Go to https://skanthak.homepage.t-online.de/download/curl-7.55.1.cab
Try this in CMD:

md c:\apps\curl
expand %userprofile%\Downloads\curl-7.55.1.cab -F:* c:\apps\curl
cd \apps\curl\AMD64

Now try:

curl -D - -fsSk http://localhost:8280/hello/Clever%20Boys
HTTP/1.1 200 OK
Accept: */*
Host: localhost:8280
Content-Type: application/x-www-form-urlencoded; charset=UTF-8
Date: Tue, 29 Aug 2017 16:35:55 GMT
Transfer-Encoding: chunked

<msg>Hello, Clever Boys!</msg>

Changing Content Type to XML

As you can see from curl's response, there is a bit exotic Content-Type of application/x-www-form-urlencoded.

To see available Content Types, look for so called MessageBuilders in c:\WSO2\wso2ei-6.1.1\conf\axis2\axis2.xml
You should see lines like:

...
<messageBuilder class="org.apache.axis2.builder.ApplicationXMLBuilder" contentType="application/xml"/>
...

Please see https://docs.wso2.com/display/EI611/Working+with+Message+Builders+and+Formatters for more details about Message Builders.

So we need to change our HelloAPI.xml to return application/xml content type:

open your HelloAPI.xml in Design tab in Eclipse Tooling
Drag&Drop Mediator -> Properties on the right side (after) Send component
Name it (for example) Set XML Content Type
Go to Properties tab and set:
- New Property Name: messageType
- Value: application/xml
- Property Scope: axis2 - important!
focus another property (for example Property Action) to ensure that your changes had been reflected.
Switch you HelloAPI.xml to Source tab and verify, that it looks like:

...
        <outSequence>
            <property description="set XML response" name="messageType" scope="axis2" type="STRING" value="application/xml"/>
            <send/>
        </outSequence>
...

press Ctrl-S to Save HelloAPI.xml
go to Servers tab and Start your Server.
Once your application is redeployed you may try curl again:

c:
cd \apps\curl\AMD64
curl -D - -fsSk http://localhost:8280/hello/Clever%20Boys
HTTP/1.1 200 OK
Accept: */*
Host: localhost:8280
Content-Type: application/xml; charset=UTF-8
Date: Wed, 30 Aug 2017 09:35:29 GMT
Transfer-Encoding: chunked

<msg>Hello, Clever Boys!</msg>

Done! Now we have correct:

Content-Type: application/xml; charset=UTF-8

Also you may try that URL http://localhost:8280/hello/Clever%20Boys in system default MSIE 8 - it should display formatted XML response (instead of Download dialog as in previous example)

Make JSON response

XML Service is fine, but today JSON data is standard (one reason is that JSON has JavaScript syntax and thus simple eval of JSON structure is enough to instantiate them.

Fortunately there already exists proper MessageBuilder for application/json content type, so just change your HelloAPI.xml property to:

...
        <outSequence>
            <property description="set XML response" name="messageType" scope="axis2" type="STRING" value="application/json"/>
            <send/>
        </outSequence>
...

redeploy (but see Resources bellow for possible troubles)
And try curl again:

C:\apps\curl\AMD64>curl -D - -fsSk http://localhost:8280/hello/Clever%20Boys
HTTP/1.1 200 OK
Accept: */*
Host: localhost:8280
Content-Type: application/json; charset=UTF-8
Date: Wed, 30 Aug 2017 16:05:04 GMT
Transfer-Encoding: chunked

{"msg":"Hello, Clever Boys!!!"}

Now we got nice JSON response. Done!

Please see https://docs.wso2.com/display/EI600/JSON+Support for more information how to fine-tune json processing in WSO2 EI.

WSO2 (or Apache Synapse) by default uses XML format for message (often even SOAP). What is noteworthy - there is no way, how to distinguish arrays in XML if there is just one element (it is ambiguous whether it is single element or the only element of array). However JSON must explicitly state what is Object and what is Array. Please see above URL for more information (the solution depends on chosen MessageBuilder.

Enabling Content negotiation

This does not work!!!

Sometimes it is useful when client may choose response format using Accept: format http header.

Enabling Content negotiation in axis2.xml:

Just ensure that this line has true value in c:\WSO2\wso2ei-6.1.1\conf\axis2\axis2.xml (should be default):

   <parameter name="httpContentNegotiation">true</parameter>

Modify your HelloAPI.xml - remove whole <property.../> element, so output channel looks like:

        <outSequence>
            <send/>
        </outSequence>

wait until application is redeployed. Sometimes you must expand Servers tab, WSO2 Enterprise Integrator 6.1.0 at localhost -> HelloServiceCompositeApplication and right-click and choose Redeploy
try these curl commands:

Resources

how to deal with 302 redeployment errors: https://stackoverflow.com/questions/41240592/error-while-creating-car-302-error-found-wso2-esb-tooling

WSO2 EI Introduction - hpaluch/hpaluch.github.io GitHub Wiki

WSO2 EI Introduction

Introduction

Requirements

Installation

Installing Oracle JDK

Installing WSO2 EI

Installing Eclipse Tooling for EI

Creating Hello World like service

Testing our new `HelloAPI`

Installing curl

Changing Content Type to XML

Make JSON response

Enabling Content negotiation

Resources

⚠️ GitHub.com Fallback ⚠️

WSO2 EI Introduction - hpaluch/hpaluch.github.io GitHub Wiki

WSO2 EI Introduction

Introduction

Requirements

Installation

Installing Oracle JDK

Installing WSO2 EI

Installing Eclipse Tooling for EI

Creating Hello World like service

Testing our new HelloAPI

Installing curl

Changing Content Type to XML

Make JSON response

Enabling Content negotiation

Resources

⚠️ **GitHub.com Fallback** ⚠️

Testing our new `HelloAPI`

⚠️ GitHub.com Fallback ⚠️