This documentation is for WSO2 Enterprise Integrator version 6.3.0 . View documentation for the latest release in the 6.x.x family and the latest release in the 7.x.x family.
Page Comparison - Quick Start Guide (v.28 vs v.29) - Enterprise Integrator Documentation - WSO2 Documentation

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

WSO2 Enterprise Integrator (WSO2 EI) is a comprehensive solution that allows you to seamlessly integrate applications, services, data, and business processes to support modern enterprise integration requirements. 

Routing requests based on message content

This is a 5-minute guide to give you a quick overview of how WSO2 EI mediates and routes messages from a front-end service (client) to a back-end service.

Let's consider a basic Health Care System where WSO2 EI is used as the integration software. In this guide, an external party (a patient) wants to make a doctor's reservation at a given hospital.

Tip

Before you begin,

  1. Download the product installer from here, and run the installer.

    Excerpt Include
    Installing the Product
    Installing the Product
    nopaneltrue

  2. If you are on a Windows OS, install cURL. For more information, see the cURL Releases and Downloads.

Let's get started!

Table of Content Zone
maxLevel4
minLevel4
locationtop

Configuring WSO2 EI

  1. Start the WSO2 ESB profile.

    Info

    The WSO2 EI product consists of many profiles. The ESB profile is used to manage short-running and stateless integrations. For more information, see WSO2 EI Overview.

    Panel
    borderColor#542989
    bgColor#ffffff
    borderWidth1
    Localtab Group
    Localtab
    activetrue
    titleOn MacOS/Linux/CentOS

    Open a terminal and execute the following command:

    Code Block
    wso2ei-6.3.0-integrator
    Localtab
    titleOn Windows
    Go to Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.3.0 Integrator. This will open a terminal and start the ESB profile.
  2. Open the ESB profile's Management Console using https://localhost:9443/carbon, and log in using admin as the username and the password.

    Info

    The Management Console provides a UI to configure WSO2 EI. WSO2 Carbon is the core platform on which WSO2 middleware products are built.

  3. Download the SampleServicesCompositeApplication_1.0.0.car file from GitHub.

    Info
    This file is a Carbon Application Archive (CAR file) containing the integration artifacts you will use in this tutorial, including:
    • An API resource, which acts as the endpoint that accepts incoming requests from a client, routes them to the back-end service for processing, receives a response from the service, and sends the response back to the client.
    • The back-end service that processes the appointment requests.
    • A Switch Mediator to route messages (based on the message content) to the relevant HTTP Endpoint defined in the ESB.
  4. Deploy the SampleServicesCompositeApplication_1.0.0.car file as follows:

    1. On the Main tab of the Management Console, go to Manage > Carbon Applications, and click Add
    2. Click Choose File, select the SampleServicesCompositeApplication_1.0.0.car file that you downloaded and click Upload

    3. Refresh the page to see the Carbon application you just added in the Carbon Applications List screen.

  5. Download the back-end service from GitHub. This will process appointment requests and copy it to the <EI_HOME>/wso2/msf4j/deployment/microservices directory. The back-end service is now deployed in the MSF4J profile of WSO2 EI. 
  6. Start the MSF4J profile. The back-end service is now started!

    Panel
    borderColor#542989
    bgColor#ffffff
    borderWidth1
    Localtab Group
    Localtab
    titleOn MacOS/Linux/CentOS

    Open a terminal and execute the following command:

    Code Block
    wso2ei-6.3.0-msf4j
    Localtab
    titleOn Windows

    Go to Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.3.0 MSF4J. This will open a terminal and start the MSF4J profile.

Sending requests to WSO2 EI

We are now ready to request a doctor's appointment at the Grand Oak Community Hospital.  

  1. Create a JSON file named request.json with the following payload, which specifies the details that are required by the back-end service to make the appointment: patient information, doctor name, hospital name, and appointment date. 

    Code Block
    languagexml
    {
      "patient": {
        "name": "John Doe",
        "dob": "1940-03-19",
        "ssn": "234-23-525",
        "address": "California",
        "phone": "8770586755",
        "email": "johndoe@gmail.com"
      },
      "doctor": "thomas collins",
      "hospital": "grand oak community hospital",
      "appointment_date": "2025-04-02"
    }
    Info

    If you want to request a different hospital, you can specify one of the following hospital names instead.

    • clemency medical center

    • pine valley community hospital

  2. Open a terminal, navigate to the directory where you have saved the request.json file, and execute the following cURL command.

    Code Block
    curl -v -X POST --data @request.json http://localhost:8280/healthcare/categories/surgery/reserve --header "Content-Type:application/json"
    Info

    This command sends the JSON payload you created in the previous step to the API resource (http://localhost:8280/healthcare/categories/surgery/reserve), which was included in the CAR file you uploaded. The API resource contains the logic for routing appointment requests to the back-end service. 

    You get the following response:

    Code Block
    languagexml
    > POST /healthcare/categories/surgery/reserve HTTP/1.1
    > Host: localhost:8280
    > User-Agent: curl/7.43.0
    > Accept: */*
    > Content-Type:application/json
    > Content-Length: 319
    > 
    * upload completely sent off: 319 out of 319 bytes
    < HTTP/1.1 200 OK
    < Accept: */*
    < Host: localhost:8280
    < Content-Type: application/json; charset=UTF-8
    < Date: Thu, 05 Jul 2018 22:21:32 GMT
    < Transfer-Encoding: chunked
    < 
    * Connection #0 to host localhost left intact
    {  "patient": {    "name": "John Doe",    "dob": "1940-03-19",    "ssn": "234-23-525",    "address": "California",    "phone": "8770586755",    "email": "johndoe@gmail.com"  },  "doctor": "thomas collins",  "hospital": "grand oak community hospital",  "appointment_date": "2025-04-02"}
  3. Now, check the terminal window and you see the following message: INFO - LogMediator message = Routing to grand oak community hospital

Congratulations, you have successfully completed this guide!
In this tutorial, you have seen how you can create a request payload and send it to an endpoint in WSO2 EI, which routes the message to a back-end service and then sends a response back to the client. 

Panel
titleWhat's next?

Additional Capabilities

Exposing a datasource as a service

Panel
borderColor#542989
bgColor#ffffff
borderWidth2
Expand
titleClick here to try it out!

Let's look at how we can check the availability of doctors in the healthcare service by sending a request. To make things simple, we have provided a database with doctors' details: You can easily set up this database and expose it as a data service using WSO2 EI. 

Follow the steps given below to check the available doctors without interacting with the database itself:

Table of Content Zone
locationtop

Set up the back-end database

First, let's set up a back-end database for our healthcare service:

  1. Download the dataServiceSample.zip file and extract it to a location on your computer.

    Info

    Let's refer to the extracted  dataServiceSample  directory as <QSG_HOME>, which contains the following:

    • A DB script to create the back-end database (DATA_SERV_QSG). This DB will contain the channeling information of the healthcare service.
    • A pre-packaged data service (DOCTORS_DataService.dbs file), which can expose the back-end database as a service.
  2. Open a terminal, navigate to the <QSG_HOME> directory, and execute the following command:

    Code Block
    ant -Ddshome=PATH_TO_EI_HOME

The  DATA_SERV_QSG  database is now created in the <EI_HOME>/samples/data-services/database directory with information of all available doctors in the healthcare service.

Expose the database as a data service

Now, let's start the ESB profile and upload the sample data service:

  1. Start the ESB profile:

    Tip

    If you have started the ESB profile previously, stop the server by pressing  Ctrl+C and restart it using the following commands.

    Panel
    borderColor#542989
    bgColor#ffffff
    borderWidth1
    Localtab Group
    Localtab
    activetrue
    titleOn MacOS/Linux/CentOS

    Open a terminal and execute the following command:

    Code Block
    wso2ei-6.3.0-integrator
    Localtab
    titleOn Windows
    Go to Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.3.0 Integrator. This will open a terminal and start the ESB profile.
  2. In your Web browser, navigate to the WSO2 EI management console using the following URL: https://localhost:9443/carbon/
  3. Log in to the Management Console using the following credentials:
    • Username: admin
    • Password: admin
  4. Go to the Main tab and click Data Service > Upload
  5. Upload the DOCTORS_DataService.dbs file from the <QSG_HOME> directory.
  6. Refresh the page to see the deployed data service in the Deployed Services screen.

The database of the channeling service is now exposed through the DOCTORS_DataService data service, which we just deployed in WSO2 EI.

Request doctors' information

Assume that you want information on the availability of all surgeons. Open a terminal and execute the following command. Note that we are specifying 'surgery' as the specialty.

Code Block
curl -v http://localhost:8280/services/DOCTORS_DataService/getDoctors?SPECIALITY=surgery

The information about the availability of all surgeons will be published on your terminal:

Code Block
languagexml
<DOCTORSLIST xmlns="http://ws.wso2.org/dataservice">
<DOCTOR>
    <NAME>thomas collins</NAME>
    <HOSPITAL>grand oak community hospital</HOSPITAL>
    <SPECIALITY>surgery</SPECIALITY>
    <AVAILABILITY>9.00 a.m - 11.00 a.m</AVAILABILITY>
    <CHARGE>7000</CHARGE>
</DOCTOR>
<DOCTOR>
    <NAME>anne clement</NAME>
    <HOSPITAL>clemency medical center</HOSPITAL>
    <SPECIALITY>surgery</SPECIALITY>
    <AVAILABILITY>8.00 a.m - 10.00 a.m</AVAILABILITY>
    <CHARGE>12000</CHARGE>
</DOCTOR>
<DOCTOR>
    <NAME>seth mears</NAME>
    <HOSPITAL>pine valley community hospital</HOSPITAL>
    <SPECIALITY>surgery</SPECIALITY>
    <AVAILABILITY>3.00 p.m - 5.00 p.m</AVAILABILITY>
    <CHARGE>8000</CHARGE>
</DOCTOR>
</DOCTORSLIST>

Congratulations, you have successfully sent a request to the data service!

Panel
titleWhat's next?

Want to know more and evaluate WSO2 EI further? See the other tutorials under the Additional Capabilities section.

Sending messages securely 

Panel
borderColor#542989
bgColor#ffffff
borderWidth2
Expand
titleClick here to try it out!

Now, instead of sending the request directly to the back-end service, you store the request message in the Message Broker profile of WSO2 EI. You use a Message Processor to retrieve the message from the store and then deliver the message to the back-end service. Store and forward messaging is used for serving traffic to back-end services that can accept request messages only at a given rate. This is also used for guaranteed delivery to ensure that a request (once received) never gets lost.

Table of Content Zone
locationtop

Let's get started!

Configuring WSO2 EI

  1. Open the <EI_HOME>/conf/jndi.properties file and add the following line after the queue.MyQueue = example.MyQueue line:

    Code Block
    queue.PaymentRequestJMSMessageStore=PaymentRequestJMSMessageStore
  2. Start the Message Broker profile to receive messages from the ESB profile.

    Panel
    borderColor#542989
    bgColor#ffffff
    borderWidth1
    Localtab Group
    Localtab
    activetrue
    titleOn MacOS/Linux/CentOS

    Open a terminal and execute the following command:

    Code Block
    wso2ei-6.3.0-broker
    Localtab
    titleOn Windows
    Go to Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.3.0 Broker. This will open a terminal and start the Message Broker profile.
  3. Download the back-end service that will process appointment requests and copy it to the <EI_HOME>/wso2/msf4j/deployment/microservices directory. The back-end service is now deployed in the MSF4J profile. 

  4. Start the MSF4J profile to send requests to the back-end service:

    Tip

    If you have started the MSF4J profile previously, skip this step.

    Panel
    borderColor#542989
    bgColor#ffffff
    borderWidth1
    Localtab Group
    Localtab
    titleOn MacOS/Linux/CentOS

    Open a terminal and execute the following command:

    Code Block
    wso2ei-6.3.0-msf4j
    Localtab
    titleOn Windows

    Go to Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.3.0 MSF4J. This will open a terminal and start the MSF4J profile.


    The Healthcare service is now active and you can start sending requests to the service.

  5. Start the ESB profile:

    Tip

    If you have started the ESB profile previously, skip this step.

    Panel
    borderColor#542989
    bgColor#ffffff
    borderWidth1
    Localtab Group
    Localtab
    activetrue
    titleOn MacOS/Linux/CentOS

    Open a terminal and execute the following command:

    Code Block
    wso2ei-6.3.0-integrator
    Localtab
    titleOn Windows
    Go to Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.3.0 Integrator. This will open a terminal and start the ESB profile.
  6. Open the ESB profile's Management Console using https://localhost:9443/carbon, and log in using admin as the username and the password.
  7. Download the SampleServicesCompositeApplication_1.0.0.car file.

    Info

    This file is a Carbon Application Archive (CAR file) containing the integration artifacts you will use in this tutorial, including:

    • An API resource, which acts as the endpoint that accepts incoming requests from a client, routes them to the back-end service for processing, receives a response from the service, and sends the response back to the client.
    • The back-end service that processes the appointment requests.
    • A Switch Mediator to route messages based on the message content to the relevant HTTP Endpoint defined in the ESB.
    • A Store Mediator to enqueues messages passing through its mediation sequence in a given message store.
  8. Deploy the SampleServicesCompositeApplication_1.0.0.car file as follows:

    Note

    Note: If you already deployed the SampleServicesCompositeApplication_1.0.0.car file when following the first part of the QSG, make sure to go to  Manage>Carbon Applications > List and delete it before proceeding to the below steps.

    1. On the Main tab of the management console, go to Manage > Carbon Applications and click Add
    2. Click Choose File, select the SampleServicesCompositeApplication_1.0.0.car file that you downloaded, and click Upload

    3. Refresh the page to see the carbon application you just added in the Carbon Applications List screen.

Sending requests to WSO2 EI

  1. Create a JSON file named request.json with the following payload, which specifies the details that are required by the back-end service to make the appointment: patient information, doctor name, hospital name, and appointment date.

    Code Block
    {
    "name": "John Doe",
    "dob": "1940-03-19",
    "ssn": "234-23-525",
    "address": "California",
    "phone": "8770586755",
    "email": "johndoe@gmail.com",
    "doctor": "thomas collins",
    "hospital": "grand oak community hospital",
    "cardNo": "7844481124110331"
    }
  2. Open a terminal, navigate to the directory where you have saved the request.json file, and execute the following cURL command.

    Code Block
    curl -v -X POST --data @request.json http://localhost:8280/healthcare/categories/surgery/reserve --header "Content-Type:application/json"
    Info

    This command sends the JSON payload you created in the previous step to the API resource (http://localhost:8280/healthcare/categories/surgery/reserve), which was included in the CAR file you uploaded. The API resource contains the logic for routing appointment requests to the back-end service you deployed. 

    You will see the response as follows:

    Code Block
    {"message":"Payment request successfully submitted. Payment confirmation will be sent via email."}
  3. Check the terminal window to see the following response:

    Code Block
    [2018-06-07 11:46:48,936] [EI-Core]  INFO - LogMediator message = Routing to grand oak community hospital
    
    [2018-06-07 11:46:48,949] [EI-Core]  INFO - TimeoutHandler This engine will expire all callbacks after GLOBAL_TIMEOUT: 120 seconds, irrespective of the timeout action, after the specified or optional timeout
    
    [2018-06-07 11:46:52,003] [EI-Core]  INFO - LogMediator To: http://www.w3.org/2005/08/addressing/anonymous, WSAction: , SOAPAction: , MessageID: urn:uuid:995e37e3-8900-4da8-8eea-67da91de2c12, Direction: request, Envelope: <?xml version='1.0' encoding='utf-8'?><soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"><soapenv:Body><jsonObject><appointmentNo>1</appointmentNo><doctorName>thomas collins</doctorName><patient>John Doe</patient><actualFee>7000.0</actualFee><discount>20</discount><discounted>5600.0</discounted><paymentID>eb83d9cc-0230-4dc8-a613-33b419cebbd7</paymentID><status>Settled</status></jsonObject></soapenv:Body></soapenv:Envelope>

Congratulations, you have successfully sent a message to the WSO2 ESB profile!

Panel
titleWhat's next?

For more information on the artifacts used in the section, you can try out the Storing and Forwarding Messages tutorial.

Defining a BPMN process

Panel
borderColor#542989
bgColor#ffffff
borderWidth2
Expand
titleClick here to try it out!

In this section, a simple BPMN process is used. It prints out a 'Hello World!' message when the process instance is initiated.

  1. Download the HelloWorldServiceTask-1.0.0.jar file that includes the defined BPMN process.

  2. Copy the JAR file to the <EI_HOME>/lib directory.

  3. Start the Business Process profile:

    Info

    The WSO2 EI product has many profiles. long-running, stateful business processes are run using the Business Process profile. For more information, see WSO2 EI Overview.

    Panel
    borderColor#542989
    bgColor#ffffff
    borderWidth1
    Localtab Group
    Localtab
    activetrue
    titleOn MacOS/Linux/CentOS

    Open a terminal and execute the following command:

    Code Block
    wso2ei-6.3.0-business-process
    Localtab
    titleOn Windows

    Go to Start Menu -> Programs -> WSO2 -> Enterprise Integrator 6.3.0 Business Process. This will open a terminal and start the Business Process profile.

  4. In a new browser window or tab, open the Business Process profile's Management Console: https://localhost:9445/carbon/
  5. Log in to the Management Console using admin for both the username and password.
  6. Download the HelloWorld.bar file.
  7. In the Management Console, navigate to the Main tab, click BPMN, and upload the HelloWorld.bar file. 
  8. Refresh the page to see the file you just added.
  9. Log into the BPMN-explorer at https://localhost:9445/bpmn-explorer using  admin  for both the username and password.
  10. Go to the PROCESS tab and click Start to start the Hello World Process.
  11. In the terminal, the "Hello World ...!!!"string is printed out. 

You have successfully defined a BPMN process and initiated it!

Panel
titleWhat's next?

Other WSO2 EI capabilities

  • In comparison with the conventional ESB profile, the start-up time of the Micro Integrator profile is considerably less, which makes it container-friendly, and thereby, is ideal to use it for microservices in a container-based environment. For more information, try out the Sending a Simple Message to a Service Using the Micro Integrator tutorial.
  • Work with WSO2 EI connectors.
  • All the CAR files that were used in this tutorial were developed using WSO2 EI Tooling. You can try it out by following the tutorials listed under Integration Tutorials.
  • Use WSO2 EI Analytics to analyze the mediation statistics. For more information, try out the following tutorial: