This documentation applies to older versions of WSO2 ESB connectors. To find the documentation relevant to the version you are using, select the connector from the WSO2 Connector Store and click Documentation.

All docs This doc

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

This section walks you through the basic structure of a connector and describes steps you need to follow when writing a connector.

Following are the high level steps you need to follow:

Table of Contents
maxLevel3

Anchor
basic
basic

...

Create the Maven project template

Execute the following command in your Command Line Interface (CLI), to generate an Apache Maven project for a sample connector code using an Maven archetype.

...

  1. To use the maven archetype to generate the Maven project template and sample connector code, run the following command in the directory where you want to create the connector on your local machine:

    Code Block
    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.

...

  1. 4 

...

  1. -DgroupId=org.wso2.carbon.esb.connector -DartifactId=org.wso2.carbon.esb.connector.

...

  1. helloworld -Dversion=1.0.0 -DarchetypeRepository=http://maven.wso2.org/nexus/content/repositories/wso2-public/

This creates the org.wso2.carbon.esb.connector.test/ directory in the current location of your machine, with a directory structure similar to the following:

folder structure of a connectorImage Removed

The directory structure includes the following files and directories.

pom.xml This contains the required dependencies for the connector core libraries, relevant Synapse libraries, and Maven repositories for a specific connector.
/assemble-connector.xml/filter.properties These files are used at the connector build time. You do not need to modify this file.
/HelloWorld.javaThis is required for integration tests of JAVA-based connectors. For information on editing it, see the example given below.
/resources/config/component.xml This is included in each module, and defines the available methods in the module.
/init.xml This is mandatory for every connector. Use this to initialize the connector environment. For example, when writing the Salesforce connector, include the login call here. You can store the Sessiontoken and API UR L returned as the response, in a property and use with other operations.
/connector.xmlThis defines the connector name and dependent modules. (i.e. the metadata of the connector)
/HelloWorld-template.xmlThis is the actual API operation calling configuration including the Synapse template of the sequence. This contains the steps necessary to call the API that is exposed by the third party. Each method of the API can be written in a manner similar to init.xml . If there is any Java code, the code should be included under Java (e.g. HelloWorld.java file), and the relevant dependencies should be added to pom.xml

After creating the Maven project template, import it to an IDE, and edit the following files.

Editing the connector.xml file

This is the main component of the ESB connector, which contains the metadata of the connector. You can add any number of resources (referred to as components) inside the resource/ directory, and include all available resources, in this connector.xml file as dependencies, to load all methods implemented in those components. Following is a sample connector.xml file.

Code Block
languagexml
<connector>
   <component name="twitter" package="org.wso2.carbon.connectors">
       <dependency component="twitter-config"/>
       <dependency component="twitter-search"/>
       <description>synapse library for twitter connector</description>
   </component>
   <icon>icon/icon-twitter-small.png</icon>
</connector>

The properties of the above connector.xml file are described below.

PropertyDescription
name

A name for the connector. This connector name should be unique, as t he connector methods will refer the connector using this as shown in the following example:
<twitter.getSearchTweets>...</twitter.getSearchTweets>

packageThe Java package, from which connectors are implemented.
componentThe resources that are available inside the resources/ directory of the folder structure.
dependency

Each dependency points to each resource/component. It will be used to load all methods implemented in the resource into the ESB.

The component property denotes the name of the resource/component. For example, "twitter-search" is the resource name of the following dependency.
<dependency component="twitter-search"/>

icon Relative path of the connector icon.

Editing the component.xml file

This file defines the metadata of the component. You can add any number of components inside the resource/ directory, and each component can have multiple methods. You need to define all methods implemented in a component in the component.xml file as sub-components, as shown in the example below.

...

languagexml

...

  1. Above is tested with Apache Maven 3.0.5.

    Note

    If maven version is 2.x.x, use the following command in the directory where you want to create the connector on your local machine:

    mvn archetype: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.connector.helloworld -Dversion=1.0.0 -DarchetypeRepository=http://maven.wso2.org/nexus/content/repositories/wso2-public/

  2. When prompted, enter a name for the connector. Specify the name in upper camel case, such as HelloWorld. Type y to confirm.

The org.wso2.carbon.esb.connector.helloworld directory is now created with a directory structure similar to the following:

Anchor
directoryStructure
directoryStructure

Image Added

The directory structure includes the following files and directories.

pom.xml
Contains the required dependencies for the connector core libraries, relevant Synapse libraries, and Maven repositories for a specific connector.
assembly
Contains files that are used at the connector build time. You do not need to modify these files.
src/main/java directoryContains any Java code for the connector.
src/main/resources directoryContains the configurations and definitions for the connector and its methods (referred to as operations). The config directory defines the initialization of the connector. You add additional directories for each category of operations (component) you want to create. In the Hello World sample, there is just one additional directory, sample, where the single operation for this sample connector is defined. However, in the ActiveCollab connector, for example, there are several component subdirectories such as activecollab-people and activecollab-projects, which contain the operations relevant to working with people and projects, respectively.
component.xml Defines the metadata for the operations in each component. You create a component.xml file in each subdirectory under src/main/resources.
sample-template.xmlDefines an operation. This is the actual API operation calling configuration including the Synapse template of the sequence. It contains the steps necessary to call the API that is exposed by the third party. For example, the ActiveCollab connector has createClient.xml and listCompanies.xml in the activecollab-people directory to define those two operations for working with people. Each operation of the API can be written in a manner similar to init.xml . If there is any Java code, the code should be included under src/main/java (e.g., the HelloWorldConnector.java file), and the relevant dependencies should be added to pom.xml.
init.xml Appears in the config directory under src/main/resources. This is mandatory for every connector and is used to initialize the connector environment. For example, if writing a Salesforce connector, include the login call here, and store the session token and API URL that are returned in the response as properties to use with other operations. For this sample, you do not need to change the file.
connector.xmlDefines the connector name and dependent modules (i.e., the metadata of the connector).
src/test directoryContains integration tests. This is required for integration tests for Java-based connectors. For more information, Perform integration tests below.

After creating the Maven project template, import it to an IDE, and edit the following files.

Edit the connector.xml file

This connector.xml file contains the metadata for the connector. You can add any number of components inside the resources directory, and then add them as dependencies in the connector.xml file to load all operations implemented in those components. Following is a sample connector.xml file.

Code Block
languagexml
<connector>
   <component name="twitter" package="org.wso2.carbon.connectors">
       <dependency component="twitter-config"/>
           <file>getSearchTweets.xml</file><dependency component="twitter-search"/>
       <description>synapse library for twitter <description>connector</description>
   </component>
           Returns a collection of relevant Tweets matching a specified query.
           </description>
       </component>
       <component name="getSavedSearchesList">
           <file>getSavedSearchesList.xml</file>
           <description>Returns the authenticated user’s saved search queries.</description>
       </component>
   </subComponents>
</component>

The properties of the above connector.xml file are described below.

PropertyDescription
name

A name for the resource/component.

type 
subComponentsAll the methods implemented in a component.
component name

The name of the method (i.e. ideally a sequence template).

fileThe name of the method file with the extension.
description

A brief description about the functionality of the method.

Editing the sample Synapse template (HelloWorld-template.xml file)

...

<icon>icon/icon-twitter-small.png</icon>
</connector>

The properties of the above connector.xml file are described below.

PropertyDescription
componentDefines the name of the connector, the package, and the components inside the resources directory that you want the connector to expose.
name

A name for the connector. This connector name should be unique, as the connector methods will refer to the connector using this name as shown in the following example:
<twitter.getSearchTweets>...</twitter.getSearchTweets>

packageThe Java package from which connectors are implemented.
dependency

Each dependency points to a component in the resources directory. It will be used to load all operations implemented in that component into the ESB.

The component property specifies the name of the component. For example, "twitter-search" is the resource name of the following dependency:
<dependency component="twitter-search"/>

iconRelative path of the connector icon.

Edit the component.xml file

The component.xml file defines the metadata of a component. You can add any number of components inside the resources directory, and each component can have multiple operations. You define all the operations implemented within a component as sub-components in the component.xml file as follows:

Code Block
languagexml
<template<component xmlnsname="http://ws.apache.org/ns/synapsetwitter-search" nametype="helloworldconnector-operationsynapse/template">
   <subComponents>
       <parameter<component name="HostAddress"/>
 getSearchTweets">
           <file>getSearchTweets.xml</file>
           <description>
  <sequence>         <log level="full">   Returns a collection of relevant      <property name="HostAddress" expression="$func:HostAddress" />
        </log>
        <class name="org.wso2.carbon.connector.HelloWorldConnector" />
    </sequence>
</template>

...

A sample configuration you can use for integration testing of JAVA-based connectors is shown below.

Code Block
languagejava
/*
*  Copyright (c) 2005-2010, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
*
*  WSO2 Inc. licenses this file to you under the Apache License,
*  Version 2.0 (the "License"); you may not use this file except
*  in compliance with the License.
*  You may obtain a copy of the License at
*
*    http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied.  See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.wso2.carbon.connector;

import org.apache.abdera.Abdera;
import org.apache.abdera.model.Document;
import org.apache.abdera.protocol.client.AbderaClient;
import org.apache.synapse.MessageContext;
import org.wso2.carbon.connector.core.*;
import org.apache.abdera.model.Entry;

public class HelloWorldConnector extends AbstractConnector {

    Abdera abdera;
    AbderaClient abderaClient;

    Document<Entry> doc;
    String HostAddress;

    public void connect(MessageContext messageContext) throws ConnectException {

        try {
            /**
             * Add your connector code here
             */
            HostAddress = getParameter(messageContext, "HostAddress").toStringTweets matching a specified query.
           </description>
       </component>
       <component name="getSavedSearchesList">
           <file>getSavedSearchesList.xml</file>
           <description>Returns the authenticated user’s saved search queries.</description>
       </component>
   </subComponents>
</component>

The properties of the component.xml file are described below.

PropertyDescription
name

The name of the component.

typeThe type of the Synapse component. These resources are Synapse templates, so the type is specified as synapse/template.
subComponents

Defines the operations in the component.

file

The name of the operation file with the extension.

description

A brief description about the functionality of the operation.

Edit the sample Synapse template (sample-template.xml file)

Each Synapse template file defines an operation. For the Hello World sample, edit the sample-template.xml file to include the Synapse configuration for the operation as follows:

Code Block
languagexml
<template xmlns="http://ws.apache.org/ns/synapse" name="helloworldconnector-operation">
    <parameter name="HostAddress"/>
    <sequence>
        <log level="full">
            <property name="HostAddress" expression="$func:HostAddress" />
        </log>
        <class name="org.wso2.carbon.connector.HelloWorldConnector" />
    </sequence>
</template>

Anchor
Sample HelloWorld.java file
Sample HelloWorld.java file
Perform integration tests

Following is sample code to perform integration tests. You can write the test methods for each connector operation in this class.

Code Block
languagejava
/*
*  Copyright (c) 2005-2010, WSO2 Inc. (http://www.wso2.org) All Rights Reserved.
*
*  WSO2 Inc. licenses this file to you under the Apache License,
*  Version 2.0 (the "License"); you may not use this file except
*  in compliance with the License.
*  You may obtain a copy of the License at
*
*    http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
* KIND, either express or implied.  See the License for the
* specific language governing permissions and limitations
* under the License.
*/
package org.wso2.carbon.connector;

import org.json.JSONObject;
import org.testng.annotations.BeforeClass;
import org.testng.annotations.Test;
import org.wso2.connector.integration.test.base.ConnectorIntegrationTestBase;
import org.wso2.connector.integration.test.base.RestResponse;

import java.util.HashMap;
import java.util.Map;

/**
 * Sample integration test
 */
public class HelloWorldConnectorIntegrationTest extends ConnectorIntegrationTestBase {

    private Map<String, String> esbRequestHeadersMap = new HashMap<String, String>();
    private Map<String, String> apiRequestHeadersMap = new HashMap<String, String>();

    @BeforeClass(alwaysRun = true)
    abderapublic =void new AbderasetEnvironment(); throws Exception {
         abderaClient = new AbderaClient(abdera);

  init("HelloWorld-connector-1.0.0");
        esbRequestHeadersMap.put("Accept-Charset", "UTF-8");
        esbRequestHeadersMap.put("Content-Type", "application/json");
   // Get}
the
Entry from Server  @Test(enabled = true, groups = {"wso2.esb"}, description = "HelloWorld test case")
    doc = abderaClient.get(HostAddress).getDocument();
public void testSample() throws Exception {
        log.info(doc.getRoot()"Successfully tested");
        }RestResponse<JSONObject> catchesbRestResponse (Exception=
e) {             throw new ConnectException(e);
   sendJsonRestRequest(proxyUrl, "POST", esbRequestHeadersMap, "sampleRequest.json");
    }
    }
}

...

Add dependencies

Add the following code to the pom.xml file , to add the dependencies.

Code Block
languagexml
<dependencies>
    <dependency>
        <groupId>org.apache.synapse</groupId>
        <artifactId>synapse-core</artifactId>
        <version>2.1.7-wso2v3-SNAPSHOT</version>
    </dependency>
    <dependency>
        <groupId>org.wso2.carbon</groupId>
        <artifactId>org.wso2.carbon.mediation.library.connectors.core</artifactId>
        <version>4.1.0</version>
    </dependency>
</dependencies>
<pluginRepositories>
    <pluginRepository>
        <id>wso2.releases</id>
        <name>WSO2 internal Repository</name>
        <url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </pluginRepository>
    <pluginRepository>
        <id>wso2.snapshots</id>
        <name>Apache Snapshot Repository</name>
        <url>http://maven.wso2.org/nexus/content/repositories/snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
        </snapshots>
        <releases>
            <enabled>false</enabled>
        </releases>
    </pluginRepository>
    <pluginRepository>
        <id>wso2-nexus</id>
        <name>WSO2 internal Repository</name>
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </pluginRepository>
</pluginRepositories>
<repositories>
    <repository>
        <id>wso2-nexus</id>
        <name>WSO2 internal Repository</name>
        <url>http://maven.wso2.org/nexus/content/groups/wso2-public/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </repository>
    <repository>
        <id>wso2.releases</id>
        <name>WSO2 internal Repository</name>
        <url>http://maven.wso2.org/nexus/content/repositories/releases/</url>
        <releases>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
            <checksumPolicy>ignore</checksumPolicy>
        </releases>
    </repository>
    <repository>
        <id>wso2.snapshots</id>
        <name>Apache Snapshot Repository</name>
        <url>http://maven.wso2.org/nexus/content/repositories/snapshots/</url>
        <snapshots>
            <enabled>true</enabled>
            <updatePolicy>daily</updatePolicy>
        </snapshots>
        <releases>
            <enabled>false</enabled>
        </releases>
    </repository>
</repositories>

...

Build the connector

Navigate to the org.wso2.carbon.esb.connector.test/ directory using your CLIhelloworld directory, and execute the following command to build the connector you created above:  maven clean install

Info

This generates the org.wso2.carbon.esb.connector.test/target/HelloWorldConnector.zip file. 

Uploading the connector to WSO2 ESB

Follow the steps below to upload maven clean install command to build the connector you created to WSO2 ESB.

  1. Log on to the ESB Management Console using the following URL and admin/admin credentials:   https://<ESB_HOST>:<ESB_PORT>/carbon/
  2. Click Main, click Manageand then  Click  Add  under the Connectors menu as shown below.  
    main menuImage Removed
  3. Click Choose File, browse and select the HelloWorldConnector.zip file, and click Upload as shown below.
    browse and upload fileImage Removed
  4. Click OK in the message, which pops-up as shown below. 
    pop up messageImage RemovedYou view the new connector added to the list of all available connectors as shown below.
    connector added to listImage Removed
  5. Click the corresponding Disbaled link of the connector, to enable it to use in WSO2 ESB as shown below. You view it being enabled as shown below.
    enable the connectorImage Removed

Now that you understand the basic structure of a connector, you can start writing your own connector, which can either be a soap-based connector, REST-based connector or a JAVA API-based connector. For more information on how you can write your own connector based on the API you have decided to use, see Connector Types.

...

This generates the org.wso2.carbon.connector.helloworld/target/HelloWorld-connector-1.0.0.zip file. 

Upload the connector to WSO2 ESB

Follow the steps below to upload the connector you created to WSO2 ESB.

Tip

You must have WSO2 ESB installed to upload a connector to WSO2 ESB via the Management Console. For information on installing WSO2 ESB, see the Installation Guide.

  1. Open the ESB Management Console, and in the Main tab under Connectors click Add. The Add Connector page opens.
  2. On the Add Connector page, click Choose File.
  3. Browse and select the HelloWorld-connector-1.0.0.zip file, and then click Upload. The following message will be displayed.
    browse and upload fileImage Added
  4. On successful upload, you will see the following message.
    pop up messageImage Added
    Click OK. You will see that the connector is added to the list of all available connectors.

For detailed information on working with connectors via the the ESB Management Console, see Working with Connectors via the Management Console.