Skip to content

Sending a Simple Message to a Service

What you'll build

Let’s try a simple scenario where a patient makes an inquiry specifying the doctor's specialization (category) to retrieve a list of doctors that match the specialization. The required information is available in a  back-end micro service.

To implement this use case, you will create a REST API resource and other artifacts using WSO2 Integration Studio, and then deploy them in the embedded WSO2 Micro Integrator instance. The default API resource will be configured to receive the client request in place of the back-end service, thereby decoupling the client and the back-end service. The response message with the requested doctor details will be routed back to the client through the same API resource.

Let's get started!

Step 1: Set up the workspace

  • Download the relevant WSO2 Integration Studio based on your operating system. The path to the extracted/installed folder is referred to as MI_TOOLING_HOME throughout this tutorial.
  • Download the CLI Tool for monitoring artifact deployments.

Step 2: Develop the integration artifacts

Follow the instructions given in this section to create and configure the required artifacts.

Create an ESB Config project

To create an ESB solution consisting of an ESB config project and a Composite Application project:

  1. Open WSO2 Integration Studio.
  2. Go to ESB Project and click Create New.

  3. Enter SampleServices as the project name. Be sure to select the following check boxes so that the relevant projects will be created.

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

  4. Click Finish.
    The created projects are saved in the Project Explorer as shown below:

Create an Endpoint

An Endpoint artifact is required for the purpose of exposing the URL that connects to the back-end service.

  1. Right-click SampleServices in the Project Explorer and navigate to New -> Endpoint.
  2. Ensure that Create a New Endpoint is selected and click Next.
  3. Enter the information given below to create the new endpoint.

    Property Value Description
    Endpoint Name QueryDoctorEP The name of the endpoint.
    Endpoint Type HTTP Endpoint Indicates that the back-end service is HTTP.
    URI Template http://localhost:9090/healthcare/{uri.var.category} The template for the request URL expected by the back-end service. In this case, the variable 'category' that needs to be included in the request for querying doctors is represented as {uri.var.category} in the template.
    Method GET Indicates that we are creating this endpoint for GET requests that are sent to the back-end service.
    Static Endpoint
    Select this option because we are going to use this endpoint only in this ESB Config project and will not reuse it in other projects.
    Note: If you need to create a reusable endpoint, save it as a Dynamic Endpoint in either the Configuration or Governance Registry.
    Save Endpoint in SampleServices This is the ESB Config project we created in the last section

  4. Click Finish.
    The QueryDoctorEP endpoint is saved in the endpoints folder within the ESB Config project you created.

Create a REST API

A REST API is required for receving the client response and the REST resource within the API will define the mediation logic that will send requests to the Healthcare back-end service and retrieve the available doctor information.

  1. In the Project Explorer, right-click SampleServices and navigate to New -> REST API.
  2. Ensure Create A New API Artifact is selected and click Next.
  3. Enter the details given below to create a new REST API.

    Property Value Description
    Name HealthcareAPI The name of the REST API.
    Context /healthcare Here you are anchoring the API in the /healthcare context. This will become part of the name of the generated URL used by the client when sending requests to Healthcare service. For example, setting the context to /healthcare defines that the API will only handle HTTP requests where the URL path starts http://:/healthcare.
    Save location SampleServices This is the ESB config project where the artifact will be saved.
    |

  4. Click Finish.

Define the mediation flow

Once the API resource is created, the design view of the HealthcareAPI.xml file will appear as shown below.

Note

  • The top part of the canvas is the In sequence, which controls how incoming messages are mediated.
  • The middle part of the canvas is the Out sequence, which controls how responses are handled. In this case, a Send mediator is already in place to send responses back to the requesting client.
  • The bottom part of the canvas is the Fault sequence, which allows you to configure how to handle messages when an error occurs (for more information, see Error Handling).

You can now start configuring the API resource.

  1. Double-click the Resource icon on the left side of the canvas.
    The properties for the API resource appear on the Properties tab at the bottom of the window. If they do not appear, you can right-click the Resource icon and click Show Properties View.
  2. On the Properties tab, provide the following as Basic properties:

    Property Description
    Url Style Click the respective Value field, click the down arrow, and then select URI_TEMPLATE from the list.
    URI-Template Enter /querydoctor/{category} . This defines the request URL format. In this case, the full request URL format is http://host:port/querydoctor/{category} where {category} is a variable.
    Methods Check if the value of Get is set to true. This defines that the API resource only handles the requests where the HTTP method is GET.

  3. You can now configure the In sequence to handle requests from the client:

    1. From the Mediators palette, click and drag a Log mediator to the In sequence (the top of the canvas).

      Note

      The Log mediator logs messages when the request is received by the In sequence of the API resource. In this scenario, let's configure the Log mediator to display the following message: “Welcome to the HealthcareService”.

    2. With the Log mediator selected, access the Property tab and fill in the information in the table below:

      Field Value Description
      Log Category INFO Indicates that the log contains an informational message.
      Log Level Custom When Custom is selected, only specified properties will be logged by this mediator.
      Log Separator (blank) Since there is only one property that is being logged, you do not require a separator. Therefore, leave this field blank.
      Properties
      To extract the stock symbol from the request and print a welcome message in the log, click the '+' icon in the Properties section, and then add the following values:
      • Name: Log Property message
      • Type: LITERAL
        (We select LITERAL because the required log message is a static value.)
      • Value/Expression : "Welcome to HealthcareService"

      Description Request Log The Description field provides the name that appears for the Log mediator icon in the design view.

    3. Click OK to save the Log mediator configuration.

    4. Configure the Send mediator to send the request message to the HealthcareService endpoint.

      1. From the Mediators palette, click and drag a Send mediator to the In sequence adjoining the Log mediator you added above.
      2. From the Defined EndPoints palette, click and drag the QueryDoctorEP endpoint, which we created, right next to the empty space of the Send mediator.

  4. Configure the Out sequence to send the response from the Healthcare service back to the client. 

    For this, we use a Send mediator with no output endpoint defined, which defaults to sending the response back to the requesting client. From the Mediators palette, click and drag a Send mediator to the Out Sequence (the bottom part of the canvas).

You have successfully created all the artifacts that are required for sending a request through the Micro Integrator to the back-end service.

Step 3: Package the artifacts

Package the artifacts in your composite application project (SampleServicesCompositeApplication project) to be able to deploy the artifacts in the server.

  1. Open the pom.xml file in the composite application project POM editor.
  2. Ensure that the following artifacts are selected in the POM file.

    • HealthcareAPI
    • QueryDoctorEP
  3. Save the project.

Step 4: Build and run the artifacts

To test the artifacts, deploy the packaged artifacts in the embedded Micro Integrator:

  1. Right-click the composite application project and click Export Project Artifacts and Run.
  2. In the dialog that opens, select the composite application project that you want to deploy.
  3. Click Finish. The artifacts will be deployed in the embedded Micro Integrator and the server will start. See the startup log in the Console tab.

Step 5: Test the use case

Let's test the use case by sending a simple client request that invokes the service.

Start the back-end service

  1. Download the JAR file of the back-end service from here.
  2. Open a terminal, navigate to the location where your saved the back-end service.
  3. Execute the following command to start the service:

    java -jar Hospital-Service-2.0.0-EI7.jar

Send the client request

Let's use the CLI Tool to find the URL of the REST API that is deployed in the Micro Integrator:

  1. Open a terminal and navigate to the CLI_HOME/bin directory.
  2. Execute the following command to start the tool: ./mi
  3. Execute the following command to find the APIs deployed in the server: mi api show

    Note: Please remember to login to CLI using mi remote login command giving admin as both username and password before executing the above command.

Now, open a command line terminal and enter the following request:

curl -v http://localhost:8290/healthcare/querydoctor/surgery

Info

  • The above request is formed as per the URI-Template (http://:/healthcare/{uri.var.category}) defined when creating the endpoint.
  • The {uri.var.category} is also specified in the URI-Template (http://<host>:<port>/querydoctor/{category})
  • Other categories you can try sending in the request are: cardiology, gynaecology, ent, and paediatric.

Analyze the response

You will see the response message from the HealthcareService with a list of available doctors and the relevant details.

[
  {"name":"thomas collins",
  "hospital":"grand oak community hospital",
  "category":"surgery",
  "availability":"9.00 a.m - 11.00 a.m",
  "fee":7000.0},
  {"name":"anne clement",
   "hospital":"clemency medical center",
   "category":"surgery",
   "availability":"8.00 a.m - 10.00 a.m",
   "fee":12000.0},
  {"name":"seth mears",
   "hospital":"pine valley community hospital",
   "category":"surgery",
   "availability":"3.00 p.m - 5.00 p.m",
   "fee":8000.0}
]

Now, check the Console tab of WSO2 Integration Studio and you will see the following message: INFO - LogMediator message = "Welcome to HealthcareService"

You have now created and deployed an API resource in the Micro Integrator, which receives requests, logs a message using the Log mediator, sends the request to a back-end service using the Send mediator, and returns a response to the requesting client.

Top