How to deploy and use WSO2 ESB Cloud Connector

In this post I describe steps on how to upload a connector to WSO2 ESB, creating a proxy and sending a request to test the functionality of the connector.

Prerequisite

• Have a bug free built connector zip file to upload to the ESB.
• Have an instance of WSO2 ESB server up and running.
• SOAP UI version 4.5 or above to test the request.

Uploading and enabling the connector in ESB

Assuming you have an up and running instance of the WSO2 ESB server, follow the below steps.

Click on Choose File button and browse the connector zip file you have.

Then click on Upload. Note if the upload is successful, the connector file name will be shown in the list and its status will be marked in red as disabled as shown below.

Click on the Status icon to make it enable.

Note:

If you get an error message while uploading the connector zip file saying the upload failed, Don't worry just refresh the page  few times and retry. If that is not caused by an error thrown by ESB server, this should work for you.

Also, you may need to wait for few seconds to enable the connector after it is uploaded. Note that if you cannot enable the connector even after few attempts, your connector may have issues, you can observe the ESB server log to check whether any exceptions are thrown. If so, carefully handle them in your connector, then build and upload again.

Creating a proxy and getting the WSDL 

Now we are done with the connector file and need to create a proxy to map the specific function call that we require to test.

You can observe there are several types of proxies shown as above. You can use Custom Proxy to define your own proxy file.

So, Click on Custom Proxy link and switch to source view from where you can handle the source of the proxy easily.

For the demonstrations purpose I am using the Github connector file and Ill focus on getPullRequest method. An example proxy file is shown below.

Proxy file content:

Click on Save. If you created the proxy with no errors, the proxy file will be listed as shown below.

If you face any error while creating the proxy, fix it and save again.

Now, to get the WSDL, you have to simply click on the WSDL1.1 link of the specific proxy.

     

Making a request through SOAP UI

In the final step, you can use the above WSDL to create a request and make an API call through the WSO2 ESB

Note that I will show how to create a REST request call since I deal with the Github REST API, You can customize your Proxy and the request in any type that suits your requirement (REST(JSON/XML), SOAP etc)

Create a New REST project in SOAP UI using the above WSDL.

Now build the REST request with the necessary parameter and valid values as shown below. Send the request and observe the output

Hope it was useful for you. If so, please leave a comment.

How to enable wire log in WSO2 ESB Server?

When working with WSO2 ESB server implementing connectors to connect to several APIs, one of the main problem I faced was the difficulty in monitoring the server while a request is sent to it from a connector. It was realized that things would be much easier if we can see how and what are the parameter going towards the ESB and what are coming from the ESB server while we make each request. 

Here comes the usage of enabling wire log in WSO2 ESB server. It's pretty simple but I hope the outcome will be so helpful to identify the behavior of the server.

Follow the simple steps. But before that make sure that you have the latest and properly running ESB in your local machine. If you want to know basic steps of running the WSO2 ESB, please follow the blog post here. 

If your ESB server is already running, make sure to follow the steps below and restart the server to apply the changes and monitor the enables wire log.

Enable the wire log as instructed below

Go to the extracted folder of the running instance of your WSO2 ESB server and move to the below shown location.

~\wso2esb-4.8.0\wso2esb-4.8.0\repository\conf

Now, open the log4j.properties file in some text editor like Notepad ++

find for the word "wire" and locate to the below shown lines of the file.

Now, uncomment the highlighted two lines that are shown in the above image. Save and close the file. You are done.

As I have already mentioned, if you already have the server instance running, do restart it to apply the changes. 

How to restart your ESB Server?

Follow the coupe of screenshots below

Hope it was useful to you. If so, please leave a comment.

How to test Google Contacts functions through Google Contacts API using Postman?

In my previous post, I have explained you how you can install Postman- Rest- Client extension in your Google Chrome Web browser and why we need such tool. In the same post, I mentioned that I will be explaining it more in another post on how to use postman to test a real world API and make sure its functionalists are working as expected. So, here we go guys.

This post is based on testing Google Contacts API functions (not all but few of them) in Postman-Rest-Client tool.

Prerequisites

• As u already know, we need to have Google Chrome running in your machine with the Postman extension installed in it.

• You must have a Google Contacts account. Don't worry, if you do have a gmail account, you will be having a Google Contacts account as well. All you need to do is to login to it at least once using the following url.

          https://www.google.com/contacts/

• Of course, you need to have Contacts in your account to start testing any function given in the api.
• You need to refer the Google Contacts API documentation well before starting to test them. The below link will direct you to the latest version of it.

          https://developers.google.com/google-apps/contacts/v3/

• The most important thing is you need to obtain an authorization access token from Google Developers' OAuth 2.0 Playground. Follow the below link to obtain it and note i will explain you how to get the access token step by step.

         https://developers.google.com/oauthplayground/

Great. Now, let's go from point zero :) 

I assume everyone has a gmail account so that a Google Contacts account too. So, let me explain you how to obtain an access token from Google Developers' OAuth 2.0 playground.

Obtaining an Autherization access token from Google Developers' OAuth 2.0 playground for Google Contacts

1.Go to the link below

 https://developers.google.com/oauthplayground/

2.

3.

4.

5.

6.

Note that the obtained access token expires within the time that is mentioned above so that you have to use that for testing before it expires. But once it's expired, you can refresh and obtain  a new access token to continue testing.

So, I hope it's clear up to this level. Next is simply to get a function, identify its parameters etc and test for it's response through postman-Rest client tool.

Before that, we have to confirm the function that we are going to test, don't we? Refer the below link and focus on the function that is highlighted in the below screenshot that is taken from the Google Contacts API documentation page.

https://developers.google.com/google-apps/contacts/v3/

Check the below shown screenshot to identify the function correctly.

How to test the Retrieve All contacts function in postman?

Open Postman-Rest-API plugin in your Google Chrome Web Browser and Click Reset button to clear any existing tests that you have been working with. Then set the below values in front of the below shown fields accordingly.

Set the url in the below format:-

https://www.google.com/m8/feeds/contacts/<your email address>/full

Add a Header call Authorization and add the value as shown below (note that your access token shouldn't be expired at the time you are using it to test):-

Bearer <the access token you obtained above>

Select the type of the http call as :-

GET

and finally click Send button to obtain the response.

for an example, refer the below screenshot

If you didn't enter an email in the request url, then the default email will be used which means the account that you have currently logged in.

I hope the post was clear enough for you to start with Postman to test API functions. Hope it was useful to you :) See you in another interesting post ...

Using WSO2 Enterprise Service Bus

In order to use the WSO2 ESB, you need to download the following.

Latest version of WSO2 ESB Binary

I use the currently available latest version which is 4.8.0 that is available in the WSO2 website. 

Click here to navigate to the downloads page and click on Binary button to start the download as shown below.

Latest version of Java Development Kit

 I use the currently available latest jdk which is jdk7.

Click here to navigate to the downloads page of Oracle to start the download. The below image could help you.

once you are done with the jdk download, you can install it and then do not forget to set the path for the bin folder and set the JAVA_HOME variable in your machine.

Setting the java path to the bin folder

Once you install jdk in your machine, do navigate to the jdk bin folder of the correct version as shown below and copy the path to it.

then type env under startup search box ( in windows) and select Edit the system environment variables option from the search results box. Next click Environment Variables under Advanced tab and then focus on path under System variables. Select it and then click Edit. Then place the cursor under variable value text box and go towards its end then add a semicolon and paste the path that you copied to clipboard (e.g :- C:\Program Files\Java\jdk1.7.0_45\bin). Then close all three opened windows by clicking OK buttons in each of them.

Note, if you don't have administrative privileges then you can temporarily set the path as below usinga command prompt (remeber you should use the correct path of your jdk bin folder)

set path=%path%;C:\Program Files\Java\jdk1.7.0_45\bin

Setting the JAVA_HOME variable

type env under startup search box ( in windows) and select Edit the system environment variables option from the search results box. under User variables for <username> panel, click New. Then add the following

Variable Name: JAVA_HOME

Variable Value: C:\Program Files\Java\jdk1.7.0_45

Then close all three opened windows by clicking OK buttons in each of them.

Note, if you don't have administrative privileges then you can temporarily set the path as below usinga command prompt (remeber you should use the correct path of your jdk bin folder)

set JAVA_HOME=C:\Program Files\Java\jdk1.7.0_45

Checking whether jdk path to bin and the JAVA_HOME variables are correctly set in your machine

open a command prompt and type,

java -version to check the java version installed is correctly identified

type,

set JAVA_HOME and observe whether the path to java home is correctly identified

Now you are ready to run the WSO2 ESB.

Running the WSO2 ESB Server

First of all, extract the wso2esb-4.8.0.zip file that you have just downloaded. then navigate to the bin folder as shown below. Meanwhile open a command prompt getting ready to run the esb sever in your machine.

use the command prompt to navigate to the bin folder which is shown above and then type,

cd C:\Users\Sherihan\Downloads\wso2esb-4.8.0\wso2esb-4.8.0\bin\wso2server.bat

and hit Enter. Or simply drag and drop the wso2server.bat in to the command prompt so that it will paste the complete file to the bat file and then hit Enter.

carefully observe the command line where it stops at a certain point providing you a URL to start the WSO2 esb server in a browser as shown below. 

Copy the url and paste it in a web browser to start the ESB server from an interface. Once it gives you the login page, enter admin as the username and admin as the password and you are ready to run the Wso2 ESB server to do what ever the required task that you wished to do with the ESB server.

Hope It was useful to you. Please leave a comment for any clarification :)