Country Lookup Service

This use case polls an email, gets the country name from the subject and calls external Webservice to get country details like Country Name, Country Code, Currency, Currency Code and sends the response as HTML, back to the caller. It also records the Action and Response into the database and writes the response to a file.

At the end of this tutorial you will be able to,

  1. Read emails via IMAP and transforming the data into required soap input format
  2. Exception Handling
  3. Call Soap Webservice and get the country details
  4. Notifying the caller when you don’t get the result
  5. Process Email details to File system and Database

Before we start the tutorial, we would need the below pre-requisites to be in place…

Please refer link Read Email and see pre-requisites section on the top.

After sorting out pre-requisites. Proceed for further steps.

1. Read new email and prepare the data to call Webservice

1. start creating new mule project

2. Mule flows are present under the src/main/app folder.

As we mentioned above, we should reply to the caller with the response coming from SOAP Webservice. Let’s create a sub flow for the same in advance so that we could use it in other flows. Add a logger into the flow to indicate we have reached this sub flow and add SMTP connector.

3.  In src/main/app path you will have the mule-app.properties file. Open it and enter the IMAP details and SMTP details needed for Gmail.

Make sure to enter your test email id and password (you created in the pre-requisites step) for IMAP.USERNAME and IMAP.PASSWORD properties respectively.

If you want to know more about configuring properties, you can refer Configuring Properties documentation of mulesoft.

4. configure SMTP connector as follows

in the security tab, enable SMTPS

 

 

Click on the ‘+’ icon beside connector configuration and configure as below

in the security tab, enable SMTPS

5. Note one more point that while using SMTPS connector, we need to add tls-client and tls-trust-store tags. your smtps connector configuration in XML should be like below

Now we have the sub-flow ready. All we have to do now would be to invoke this sub-flow whenever we need to send a mail.

 

6. Then, start with our new flow, from the Mule Palette drag the IMAP connector. Follow below steps to configure the IMAP inbound endpoint.

1. Click on IMAP connector then, In the General tab, Basic settings, observe that we are getting the value for Host, Port, Username and Password from the mule-app.properties file (from the previous step). Refer below; Figure 2: General Settings. Click on Security tab and enable IMAPS. (Refer Figure 1: Security tab ).

Figure 1: General settings

Figure 2: Security Tab

2. Click on the ‘+’ icon beside connector configuration. Enter your mailbox folder (Refer Figure 3: Connector Configuration – General). Go to security tab and enable IMAPS. (Refer Figure 4: Connector Configuration – Security). Click OK.

Figure 3: Connector Configuration – General

Figure 4: Connector Configuration- Security tab

7. Create 2 new session variables after IMAP connector to store from address and subject.

8.  We will add choice component to check and validate the email subject. For this use case,  we expect to receive a mail with the subject as Get Currency <Currency-Name> (e.g.,Get Currency Germany, Get currency India)

In the coming steps, we will be validating the same using choice in mule.

1. Create a new sub-flow called country_lookupSub_flow. Let it be empty for now we will be adding required message processors soon.

2. Add the below choice component after the two session variables that we just created.

3. As you see we check if the subject contains Get Currency. If so we route to the currently empty country_lookupSub_flow after setting the payload with the Country Name.

4.Else if we receive invalid subject, we call the send_response sub-flow after setting the payload as ‘Invalid Request’

5.Below is how checkForEmailSubject flow would look like till this stage

2. Exception Handling

1. Drag a Catch Exception Strategy in the exception part of checkForEmailSubject flow

2. Add a logger to log the error message

3. Set the payload with the error message and payload at the time error occurred.

4. Add a flow reference to send_response flow so that the sender will get notification of the exception

Below is the configuration XML part for catch exception strategy

Below is how the flow looks with exceptions being handled.

We have added catch exception strategy to catch the exceptions thrown by this flow. For example, In choice component, after setting the payload to country name it will go to country_lookupSub_Flow. There we may encounter exceptions while connecting with the database such as wrong database name(syntax error) or while loading wsdl etc.. We will test the exception scenarios in Testing part.

3. Call Webservice and get Country Details

1. In checkForEmailSubject flow, we have the country name as payload for country_lookupFlow. Now, In country_lookupFlow, drag and drop Webservice consumer. Here observe that we are giving the string as payload but, we need to provide XML input to call soap webservice. so, add transform message component before webservice.

2. Now, click on Transform message component. In output section, We will see meta data generated automatically.

3. Now, we have to map our payload to this output. For this double click on ns0:CountryName:String (see below figure), it will generate metadata in right side output panel and it shows you country name with “null”.

4. Now, at the place of “null” write “payload” so that CountryName to request would be our payload value that we are giving.

5. Now, you configured your input successfully. Let’s proceed. click on Webservice consumer connector of our flow.

6. click on Connector Configuration plus icon on right. It will ask you to provide WSDL location. add WSDL link
http://www.webservicex.net/country.asmx?WSDL it will automatically generate service name as a country.

7. Select port whichever you want. I have selected countrysoap.Then, it will generate Address accordingly.

8. In General Settings of Webservice Consumer, it will show you different Soap operations. Here, select operation GerCurrencyByCountry

When you run the flow, you will get the output as type “org.mule.module.ws.consumer.NamespaceRestorerXMLStreamReader@6814b35a”

9. To get the output in required XML format add transform message component after Webservice consumer.

after that click on transform message component. In input section, it will show you payload with GetCurrencyByCountryResponse.

. 10. Now, map this payload to our simple string format. Like below define metadata.

Add type id e.g., response

select metadata type as a simple string then click ok.

Now, map(drag) our payload to this string.

in output panel, you will see like below.

11. when you run this code you will get XML format like below

Observe that, in this XML code “XML declaration” is not there. For further steps, to work properly add XML declaration in output panel like below.

‘<?xml version=”1.0″ encoding=”UTF-8″?>’

see below figure.

4. Notifying the caller when we don’t get the result

  1. To convert the response in HTML format. We will add XSLT transformer after transform message component.
    for this conversion, we have to provide a .xslt file to get our required form.
    .xslt should look like below.
  2. Create a new sub-flow named processRecords. Let it be empty as of now we will be adding message processors to it shortly.
  3. Add a choice component within country_lookupsub_Flow flow after transform message component.
  4. Carefully examine the when expression. You see that we check the payload to know if it has the NODE ‘Table’. This tells us that Webservice response contains data. If the condition is true meaning we have received country details from soap webservice, then we proceed to the processRecords sub-flow.
  5. Else we send a response back to the caller saying, ‘No Records Found’
  6. We have now completed the country_lookupsub_Flow,.

We had created processRecords sub-flow. Let’s add the components to it so that we record the response, subject etc into the filesystem and database

5. Process Email details to Filesystem and Database

1. We had created processRecords sub-flow. Let’s add the components to it so that we record the response, subject etc into the filesystem and database. Drag a file endpoint into the processRecords sub-flow and configure it as shown below.

 

2.Store information into database and send XML response to the caller

1. Add a scatter-gather component after File Connector.
Scatter-Gather component sends the same message to multiple message processors or outbound endpoints in parallel.

2. Drag a logger component and a flow-reference component (referring send_response) into the scatter gather (should be one below the other)

3. Drag a database component after logger.

4. In the pre-requisite steps, we have created a database table EMAILREQUEST
Let’s configure the database connector to insert the response into EMAILREQUEST table

5. Configure the database connector as shown below.

6.Then, click on Connector configuration plus(+) icon

3. We have now successfully entered data into the database and have sent the response XML back to the caller.

4. Add a logger component after scatter gather to log success

The processRecords sub-flow would look as shown below.

Complete configuration of this project in XML is

Complete code you can download from link
https://bitbucket.org/integralzone/blog/src/f3e970d1042b63b476570bb8ccd7b5ad9aef062b/country_lookup/?at=master

Testing

  1. Right Click on the project and Run As Mule application. Wait till the application starts up.
  2. Then send an email to test email with the subject “Get Currency India”. In file system, you will get the output as
  3.  Check the response in your inbox. It should have come like below

    Yes!! We have received the employee details as expected.
  4. Before we end this use case, test the exception scenario for better understanding. For this purpose, give wrong database name to see how exceptions are getting thrown. See I have given my database name as emailreques(instead of emailrequest).
  5. Then check the console after running the project.

  6.  Check your email now. In exception handling section, we have set the payload with the error message. So, with our actual payload error message also got attached like below.

Lessons learned from this use case

– Understanding of how web services work and SOAP messages work
– Working with choices in mule
– Exception handling