WSO2 Enterprise Integrator 7 min

Creating a Custom Connector in WSO2 EI 6.1.1

Rob Blaauboer
Rob Blaauboer
Integration Consultant & WSO2 Trainer
Custom connector wso2 ei

Custom connector wso2 ei.jpegConnectors are becoming more and more important in the WSO2 EI. It started with the creation of the WSO2 Store for ESB connectors (store.wso2.com) where you can find more and more connectors (over 150 at this moment for the ESB) that will allow you to easily connect to a 3rd party system online (or if you prefer, in the cloud). In case your favorite online service does not have a connector, with WSO2 you can perfectly build a custom connector yourself. In this blog I’ll tell you how.

This blog is an updated version of a previous blog for the WSO2 Enterprise Service Bus 5.0.0.

What is a connector?

A connector is, at a high level, a bundling of interface descriptions that will allow you to access a third party system. API’s are the most common incarnation of connectors but Java and SOAP are alternatives that can be used in a connector.

The mechanism behind it is simple: a structure that functionally bundles a number of specific interfaces (stored in directories) and an XML file structure (connectors and components) to make it machine readable.

How do you create a custom connector?

To create a custom connector  you need to do the following:

  • Research the APIs provided by the service for which you want to create a connector.
  • Decide which API you are going to use to write the connector. For example, JIRA provides a REST API and Java API. If you choose the REST API, you can create your connector and operations entirely from XML configuration files. If you choose a Java API, you create XML configuration files that define your connector and point to your Java classes that define the operations.
  • Use the connector core libraries to write your connector.
  • After you create the files, you package them in a ZIP file, which you can then add to an ESB instance.

Detailed instructions

We will create the connector on the desktop without using Eclipse / Developer Studio. We assume a Linux based environment but for Windows it is basically the same. We create a simple Google Books API.

Open a terminal session, for instance on the desktop.

We create the required template using the maven archetype, and run the following command to generate the maven project sample connector code:

mvn org.apache.maven.plugins:maven-archetype-plugin:2.4:generate -DarchetypeGroupId=org.wso2.carbon.extension.archetype -DarchetypeArtifactId=org.wso2.carbon.extension.esb.connector-archetype -DarchetypeVersion=2.0.4 -DgroupId=org.wso2.carbon.esb.connector -DartifactId=org.wso2.carbon.esb.connector.googlebooks -Dversion=1.0.0 -DarchetypeRepository=http://maven.wso2.org/nexus/content/repositories/wso2-public/

We have put googlebooks in RED since it indicates the name of the directory that is created.

When you are generate the maven project sample connector code, it will prompt for a name for the connector. Specify the name of the connector in lower case. For example, googlebooks.

This creates within the org.wso2.carbon.esb.connector.googlebooks directory a number of artifacts for the in the current location of your machine.

Google Books API - Custom Connector WI 6.1.1.png

In this example, we will use Google Books API so specify connector name as googlebooks when asked. Enter Y to confirm.

Custom Connector EI 6.1.1 pom.xml.png

The structure is now created and by default will create a tree structure with a pom.xml, src tree and repository tree. We will add and configure files in the /src/main/resources directory.

Start by removing the sample directory.

Create a volume directory in /resources. Here we will place two files.

create volume directory in resources - custom conector EI 6.1.1.png

Following Synapse template is providing the service at list volume.

This should be placed under /src/main/resources/volume directory as listVolume.xml.

<template name="listVolume" xmlns="http://ws.apache.org/ns/synapse">
       <parameter name="searchQuery" description="Full-text search query string." />
              <property name="uri.var.searchQuery" expression="$func:searchQuery" />
<http method="get"
uri-template="https://www.googleapis.com/books/v1/volumes?q={uri.var.searchQuery}" />


Create a component.xml file in volume directory with the following content. This file contains information about the operations in one category.

<?xml version="1.0" encoding="UTF-8"?>
<component name="googlebooks_volume" type="synapse/template">
        <component name="listVolume">
            <description>List volumes matching for the given query.</description>

Modify the connector.xml file by adding new dependency as below

<?xml version="1.0" encoding="UTF-8"?>
       <component name="googlebooks"

              <dependency component="config" />
              <dependency component="googlebooks_volume" />
              <description>wso2 sample connector library</description>       </component>

The config directory can stay as is since we do not need to login to the service in this example. 

Build the code

We can now build the connector code using Maven.

run mvn clean install

from org.wso2.carbon.connector.googlebooks directory

Upload googlebooks.zip file from the target directory. You can upload this zip file through the ESB interface under connector category. Enable the connector after uploading.

Now you can define proxy service to invoke implemented connector.

Go to Home>Manage>Services>Add>Proxy Service>Custom Proxy>switch to source view and paste the following:

<?xml version="1.0" encoding="UTF-8"?>
<proxy xmlns="http://ws.apache.org/ns/synapse" name="googlebooks_listVolume"
       transports="https,http" statistics="disable" trace="disable"

                      <property name="searchQuery" expression="json

                      <respond />
                      <log />
                      <send />
       <description />

Using a REST client (e.g. Advanced Rest Client), POST the following request body at http://localhost:8280/services/googlebooks_listVolume. Also, set the Content-Type to application/json.  { “searchQuery”:”wso2″} 

request body - custom connector ei 6.1.1png.png

Advanced Rest Client - custom connector ei 6.1.1.png

Connectors are an easy way to make a connection to an external service. Using an existing connector from WSO2 will save you a lot of time figuring out how to connect and work with the online service. In case your favorite online service does not have a connector you can build one yourself. In case you are an online service provider and would like to have your service available to users as a connector it is good to know that you can submit  the connector to WSO2 for review and potential addition to the WSO2 store. 

Any questions regarding this blog? Please leave a comment. Do you want to learn more about WSO2? Sign up for one of our trainings by clicking the button below!



Microservices for the Enterprise

Get it now
We appreciate it
Care to share

Please select one of the social media platforms below to share this pages content with the world