WSO2 Integration Cloud

All docs This doc
Expand all   Collapse all
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.

This guide walks 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 start by downloading WSO2 Integration Studio to develop your WSO2 ESB Composite Application:

 Getting started with WSO2 Integration Studio

  1. Download the appropriate WSO2 Integration Studio distribution for your operating system.

  2. Extract the downloaded file to get the IntegrationStudio application. If you are a MacOS user, be sure to add it to the Applications directory.
  3. Run the IntegrationStudio application to start the tool. 

  4. Go to ESB Project and click Create New. 

  5. Give a project name (e.g., SampleProject) and be sure to select the following check boxes so that the relevant projects will be created.

    • Create Registry Resources Project
    • Create Connector Exporter Project
    • Create Composite Application Project

  6. 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 Project Explorer, right click on your project (e.g., SampleProject), click New and then click Endpoint.


  2. On the New Endpoint Artifact dialog box that is displayed, select Create A New Endpoint and click Next.

  3. Specify the following details to create the endpoint artifact:


  4. Click Finish.

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

    Endpoint NameEndpoint TypeURI TemplateMethodStatic/DynamicSave in
    channellingFeeHTTP http://wso2training-restsamples.wso2apps.com/{uri.var.hospital.name}/categories/appointments/{uri.var.appointment_id}/fee GETStatic<Your sample project>
    discountEligibilityHTTP http://wso2training-restsamples.wso2apps.com/{uri.var.hospital.name}/categories/patient/appointment/{uri.var.appointment_id}/discount GETStatic<Your sample project>
    getPaymentDetailsHTTP http://wso2training-restsamples.wso2apps.com/healthcare/payments/payment/{uri.var.payment_id}GETStatic<Your sample project>
    settlePaymentHTTP http://wso2training-restsamples.wso2apps.com/healthcare/payments POSTStatic<Your sample project>

  6. Under SampleProject -> src -> main -> synapse-config -> endpoints, click each endpoint that you created in the previous step, click their Source tab, and replace each of the existing code blocks with the respective code block given below:

    Endpoint XMLSource Code
    reserveAppointmentEp.xml
    <?xml version="1.0" encoding="UTF-8"?>
<endpoint name="reserveAppointmentEp" xmlns="http://ws.apache.org/ns/synapse">
    <http method="post" uri-template="http://wso2training-restsamples.wso2apps.com/{uri.var.hospital.name}/categories/{uri.var.category}/reserve"/>
</endpoint>
    channellingFee.xml
    <?xml version="1.0" encoding="UTF-8"?>
<endpoint name="channellingFee" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://wso2training-restsamples.wso2apps.com/{uri.var.hospital.name}/categories/appointments/{uri.var.appointment_id}/fee"/>
</endpoint>
    discountEligibility.xml
    <?xml version="1.0" encoding="UTF-8"?>
<endpoint name="discountEligibility" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://wso2training-restsamples.wso2apps.com/{uri.var.hospital.name}/categories/patient/appointment/{uri.var.appointment_id}/discount"/>
</endpoint>
    getPaymentDetails.xml
    <?xml version="1.0" encoding="UTF-8"?>
<endpoint name="getPaymentDetails" xmlns="http://ws.apache.org/ns/synapse">
    <http method="get" uri-template="http://wso2training-restsamples.wso2apps.com/healthcare/payments/payment/{uri.var.payment_id}"/>
</endpoint>
    settlePayment.xml
    <?xml version="1.0" encoding="UTF-8"?>
<endpoint name="settlePayment" xmlns="http://ws.apache.org/ns/synapse">
    <http method="post" uri-template="http://wso2training-restsamples.wso2apps.com/healthcare/payments"/>
</endpoint>

  7. Save your changes.

 Creating the sequences
  1. In the Project Explorer, right click on your project (e.g., SampleProject), click New, and then click Sequence.

  2. On the New Sequence Artifact dialog box that is displayed, select Create New Sequence and click Next.

  3. Specify the Sequence Name as faultSequence.

  4. Click Finish.

  5. Go to the Source tab of the new sequence and replace the existing code with the following:

    <sequence xmlns="http://ws.apache.org/ns/synapse" 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"/>
  </log>
  <payloadFactory description="" media-type="json">
     <format>
        { "Status":"Error Occurred While Processing the Request", "Message":"$1" }
     </format>
     <args>
         <arg evaluator="xml" expression="get-property('ERROR_MESSAGE')"/>
     </args>
  </payloadFactory>
  <respond/>
</sequence>

  6. Save the code, and then go to the Design tab to understand how you can also create these sequences by dragging and dropping the components from the Palette in the Design view and appropriately changing values of the properties under the Properties section.

  7. Similarly, create another sequence by the name APIInSequence and then go to the Source tab of the sequence and replace the existing code with this code.

 Creating the REST API
  1. In the Project Explorer, right click on your project (e.g., SampleProject), click New, and then click REST API.
  2. On the New Synapse API dialog box that is displayed, select Create A New API Artifact and click Next.

  3. Specify the following values
    • Name: HospitalServiceApi
    • Context:  /hospitalservice

  4. 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="http://ws.apache.org/ns/synapse">
    <resource faultSequence="faultSequence" inSequence="APIInSequence" methods="POST" url-mapping="/reserve">
        <outSequence/>
    </resource>
</api>
  5. Save all your changes.
 Exporting the artifacts into a CAR file

Now that you have completed 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 Project Explorer, right click SampleProjectCompositeApplication and then click Export Composite Application Project.
  2. Select a destination folder to save the CAR file 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 via http://wso2.com/cloud/. The UI will guide you through the registration process.
  2. Sign in to WSO2 Integration Cloud, go to the Integration Cloud tab, and then click ESB Composite Application.

  3. On the screen that is displayed, click CREATE APPLICATION.
  4. Under Integration, click WSO2 ESB Composite Application. 
  5. Specify the following as values:
    • Application Name: SampleProjectCompositeApplication
    • Application Version: 1.0.0
  6. Upload the CAR file that you created in the previous section. If you did not create the project from scratch, use this file.


  7. Once the application is created, its homepage opens.

You have now deployed an ESB service in WSO2 Integration Cloud using an archive file. Next, let's invoke this application.

Invoking your application

Let's invoke the 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": "marksm@mymail.com"
       },
       "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 "https://companyn-sampleprojectcompositeapplication.wso2apps.com/hospitalservice/reserve" --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 list 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 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