All docs
This doc
This section walks you through the basic structure of a connector and describes how you can write your own connector based on the API you have decided to use.
The basic structure of a connector
Use your IDE to create a Maven project, and create a directory structure similar to the following:
| 1 | connector.xml | This defines the connector name and dependant modules. (i.e., the metadata of the connector) |
| 2 | component.xml | This is included in each module, and defines the available methods in the module. |
| 3 | init.xml | This is mandatory for every connector By using this, you can initialize the connector environment. For example, when writing the Salesforce connector, login call can be included here. Sessiontoken and API URL returned as the response can be stored in a property and used with other operations. |
| 4 | assemble-connector.xml/filter.properties | These files are used at the connector build time. You do not need to modify this file. |
| 5 | pom.xml | This contains the required dependencies for the connector core libraries, relevant synapse libraries as well as maven repositories for a specific connector. |
| 6 | <operation-name>.xml | This is the actual API operation calling configuration. 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 and the relevant dependencies should be added to pom.xml |
You need to create the required template using the maven archetype https://github.com/wso2-extensions/archetypes/tree/master/esb-connector-archetype, and then run the following command to generate the maven project sample connector code:
mvn archetype:generate -DarchetypeGroupId=org.wso2.carbon.extension.archetype -DarchetypeArtifactId=org.wso2.carbon.extension.archetype.esb.connector-archetype -DarchetypeVersion=1.0.0 -DgroupId=org.wso2.carbon.esb.connector -DartifactId=org.wso2.carbon.esb.connector.test -Dversion=1.0.0 -DarchetypeRepository=http://maven.wso2.org/nexus/content/repositories/wso2-public/
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.
<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.
| Property | Description |
|---|---|
name | A name for the connector. This connector name should be unique, as the connector methods will refer the connector using this as shown in the following example: |
package | The Java package, from which connectors are implemented. |
component | The 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 |
icon | Relative path of the connector icon. |
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.
<component name="twitter-search" type="synapse/template">
<subComponents>
<component name="getSearchTweets">
<file>getSearchTweets.xml</file>
<description>
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.
| Property | Description |
|---|---|
name | A name for the resource/component. |
type | |
subComponents | All the methods implemented in a component. |
component name | The name of the method (i.e. ideally a sequence template). |
file | The name of the method file with the extension. |
description | A brief description about the functionality of the method. |
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 these connector types, see Connector Types.
Overview
Content Tools
Activity