Try WSO2 Cloud for Free
Sign in

All docs This doc
Skip to end of metadata
Go to start of metadata

WSO2 Integration Cloud is a runtime that allows you to deploy different types of applications and services, manage their versions, host  databases, connect to external Cloud services, and manage other  integration requirements of your connected business.

In this guide, we walk you through the basic functionality of WSO2 Integration Cloud using WSO2 ESB Composite Application type as an example.

Introducing the sample

In this guide, we use a sample in a healthcare system in which a user reserves a medical appointment by providing his/her personal details, preferred hospital, doctor's name, credit card information etc. Your application processes the user's request and returns an appointment confirmation or a refusal. 

Developing your application

Let's see how you can start by first developing your WSO2 ESB Composite Application using WSO2 ESB Tooling:

 Getting started with ESB Tooling
  1. Go to , select WSO2 Enterprise Service Bus version 5.0.0 from the drop-down list, and download the tooling build that is suitable for your operating system.
  2. Are you on Ubuntu 16.04? If so, in the eclipse.ini file, add a line as "--launcher.GTK_version" before the line "–launcher.appendVmargs". This is required due to a known issue in the GTK shipped with Ubuntu 16.04.

  3. To open the Tooling interface, uisng a command-prompt or terminal, go to the location where you extracted the ESB tooling ZIP file, and run the following command:

  4. Once the Tooling interface opens, click File -> New ->   ESB Solution Project.

  5. Give a project name (e.g., SampleProject) and click Finish.

 Creating the backend services

The backend services used in this guide are hosted in  WSO2 Integration Cloud . Let's create endpoints for these services and expose those URLs so that you can connect to the backend services using those URLS.

  1. In the Tooling interface, right click your project (e.g., SampleProject) and click New -> Endpoint.
  2. From the pop-up window, select Create A New Endpoint and click Next.

  3. Fill in the form with the following details and click Finish.

  4. Similarly, create all of the endpoints listed in the following table:

    Endpoint NameEndpoint TypeURI TemplateMethodStatic/DynamicSave in
    channellingFeeHTTP{}/categories/appointments/{uri.var.appointment_id}/fee GETStatic<Your sample project>
    discountEligibilityHTTP{}/categories/patient/appointment/{uri.var.appointment_id}/discount GETStatic<Your sample project>
    getPaymentDetailsHTTP{uri.var.payment_id}GETStatic<Your sample project>
    settlePaymentHTTP POSTStatic<Your sample project>
  5. Under src -> main -> synapse-config -> endpoints, click each endpoint that you created in the previous step, click their Source tab, and replace the existing code blocks with these:

    Endpoint XMLSource Code
    <?xml version="1.0" encoding="UTF-8"?>
    <endpoint name="reserveAppointmentEp" xmlns="">
        <http method="post" uri-template="{}/categories/{uri.var.category}/reserve"/>
    <?xml version="1.0" encoding="UTF-8"?>
    <endpoint name="channellingFee" xmlns="">
        <http method="get" uri-template="{}/categories/appointments/{uri.var.appointment_id}/fee"/>
    <?xml version="1.0" encoding="UTF-8"?>
    <endpoint name="discountEligibility" xmlns="">
        <http method="get" uri-template="{}/categories/patient/appointment/{uri.var.appointment_id}/discount"/>
    <?xml version="1.0" encoding="UTF-8"?>
    <endpoint name="getPaymentDetails" xmlns="">
        <http method="get" uri-template="{uri.var.payment_id}"/>
    <?xml version="1.0" encoding="UTF-8"?>
    <endpoint name="settlePayment" xmlns="">
        <http method="post" uri-template=""/>
  6. Save your changes.

 Creating the sequences
  1. In the Tooling interface, right click your project (e.g., SampleProject) and click New -> Sequence.
  2. Create a new sequence by the name  faultSequence and click Finish.

  3. Go to the Source tab of the new sequence and replace the existing code with this one:

    <sequence xmlns="" name="faultSequence" trace="disable">
      <log level="custom">
         <property name="FaultMessage" value="Fault Sequence Executed"/>
         <property xmlns:ns="http://org.apache.synapse/xsd" expression="get-property('ERROR_MESSAGE')" name="ERROR_MESSAGE"/>
      <payloadFactory description="" media-type="json">
            { "Status":"Error Occurred While Processing the Request", "Message":"$1" }
             <arg evaluator="xml" expression="get-property('ERROR_MESSAGE')"/>
  4. Save the code, go to the Design tab, and note that you can also create these  sequences by dragging and dropping the components from the Palette in the Design section and changing the values of the properties under the property section.

  5. Similarly as above, create another sequance by the name APIInSequence and add this code in the APIInSequence.xml file.

 Creating the REST API
  1. In the Tooling interface, right click your project (e.g., SampleProject) and click New -> REST API.
  2. Create a new REST API by the name  HospitalServiceApi and context  /hospitalservice.
  3. Go to the  Source  tab of the  HospitalServiceApi.xml file and replace the existing code with the following:

    <?xml version="1.0" encoding="UTF-8"?>
    <api context="/hospitalservice" name="HospitalServiceApi" xmlns="">
        <resource faultSequence="faultSequence" inSequence="APIInSequence" methods="POST" url-mapping="/reserve">
  4. Save all your changes.
 Exporting the artifacts into a CAR file

Now that you have done building your ESB Composite Application, let's export it into a CAR file. A Composite Application (CAR) is an archive file that has the collection of artifacts that you want to deploy in a WSO2 product instance. These artifacts are usually JAVA-based or XML configurations, designed differently for each product in the WSO2 Carbon platform. You can deploy these artifacts to generate services.

  1. In the Tooling interface, right click SampleProjectCompositeApplication and click Export Composite Application Project.
  2. Give a destination folder to create the CAR file in and click Next.
  3. Select your project from the Artifacts section, and click Finish.

Deploying your application

Now that you have developed an ESB composite application, let's deploy it in WSO2 Integration Cloud.

  1. Sign up to WSO2 Integration Cloud by going to The UI will guide you through the registration process.
  2. Sign in to the Integration Cloud and go to the Integration Cloud tab. Then, click ESB Compsite Application.
  3. Select the Local File System option and click Continue.
  4. Enter the following information in the form that opens, scroll down, and click Create
    • Application Name: SampleProjectCompositeApplication
    • Upload the CAR file that you created in the previous section. If you do not want to create from scratch, use this file.
  5. Once the application is created, its homepage opens.

You have now deployed an ESB service in WSO2 Integration Cloud from an archive file. Let's invoke this application.

Invoking your application

Let's inoke your application's REST endpoint.

  1. Click the Swagger URL that is associated with the application to open the Swagger definition in your browser.
  2. Note the Swagger definition of the REST API that opens.

    According to the Swagger definition, let's create an appointment request to the REST API.

  3. Create a JSON file named reserve_appointment.json with the following request:

       "reserveRequest": {
           "patientDetails": {
               "name": "Mark Smith",
               "dob": "1990-03-19",
               "ssn": "ASJK-asnda-AAA",
               "address": "100 MAIN ST, SEATTLE WA 98104, USA",
               "phone": "0770596754",
               "email": ""
           "doctor": "thomas collins",
           "hospital": "grand oak community hospital",
           "category": "surgery",
           "cardNo": "7844481124110331"
  4. Install curl in your machine if you have not done so already.

  5. Using the Command-line or Terminal, navigate to the location where you saved the reserve_appointment.json file and execute the following curl command. You can get the <REST API URL> from the application's Overview page.

    curl -v -X POST "<REST API URL>/reserve" --header "Content-Type: application/json" -d @reserve_appointment.json -k -v
    Here's an example:
    curl -v -X POST "" --header "Content-Type: application/json" -d @reserve_appointment.json -k -v
  6. The configuration inside WSO2 ESB receives and processes the request and give a response similar to the one below:

You have now invoked the REST endpoint of the ESB Composite application. 

Creating a new version

Let's say you want to make a modification to the current application. You can do this by changing your application via the Tooling interface as you did in a previous section, exporting the modified application as a CAR file, and then uploading the new CAR file as the new version of your current application back in the Integration Cloud.

Assuming that you already have the modified your application and got the CAR file, let's create a new version of the application.

  1. Open the Integration Cloud and click the application that you want to version. In this example, it is the SampleProjectFromFileSystem application.
  2. The application opens on the console. Click the + icon right next to the versions drop-down to create a new version of the application.
  3. Select the Local File System option and click Continue.

  4. In the form that opens, give the new version (e.g., 2.0.0), upload the new archive file, scroll down, and click Create.

  5. The new application version opens on the console. Note that version 2.0.0 is selected in the drop-down box on the console.

  6. Click the drop-down box and note that both versions are available for the application. 

You have now deployed a new version of an existing application using an archive file. You can invoke this version by selecting version 2.0.0 from the drop-down and following the same steps as before.

Updating an existing version

Sometimes, after creating an application, you might want to do modifications to it without creating a new version altogether. 

  1. Open the Integration Cloud and click the application that you want to update (e.g., SampleProjectCompositeApplication).
  2. The application opens on the console. Click the down-arrow near the version drop-down and select version 2.0.0 of the application. This is the version that we are updating in this example. 
  3. Click Update
  4. Note that you are given several options to update. Le's use the Update from Local File System option in this guide.

  5. Upload the new sample file with the changes you want to add to the application, provide a reason for the update in the comments section, and click Update.

  6. Note that for version 2.0.0, which you just updated, the button name changes to Update or Rollback.

  7. Click the Update or Rollback button and note that you can revert to any of the previous applications (in this case, there is only one) or you can do further updates to the application. Each update you do is saved in history so that you can revert back anytime you like.

You have now updated an existing version of an application using an archive file.

In this guide, you developed a sample ESB composite application, deployed it WSO2 Integration Cloud, invoked, and versioned it.

What's next?

See our Tutorials or Integration Solutions for more advanced business use cases.

  • No labels