This documentation is for WSO2 Enterprise Service Bus version 4.8.0 . View documentation for the latest release.

All docs This doc
Skip to end of metadata
Go to start of metadata

A connector is a collection of templates that define operations users can call from their ESB configurations to easily access specific logic for processing messages. Typically, connectors are used to wrap the API of an external service. For example, there are several default connectors provided with the ESB that call the APIs of services like Twitter and JIRA. You can also create your own connector to provide access to other services. Creating a connector involves the following high-level tasks:

  1. Research the APIs provided by the service for which you want to create a connector.
  2. 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.
  3. Use the connector core libraries to write your connector. 
  4. After you create the files, you package them in a ZIP file, which you can then add to an ESB instance.

This page describes the structure of the configuration files you create for your connector, and best practices for creating connectors.

Creating the configuration files

Use your IDE to create a Maven project, and create a directory structure similar to the following:

Following is a description on the required files shown above.

  • pom.xml - Contains the required dependencies for the connector core libraries and relevant Synapse libraries, as well as Maven repositories for the specific connector (such as JIRA Maven repositories for a JIRA connector). 

    <dependencies>
      <dependency>
        <groupId>org.wso2.carbon</groupId>
        <artifactId>org.wso2.carbon.mediation.initializer</artifactId>
        <version>${project.version}</version>
      </dependency>
      <dependency>
        <groupId>org.wso2.carbon</groupId>
        <artifactId>org.wso2.carbon.connector.core</artifactId>
        <version>${project.version}</version>
      </dependency>
      <dependency>
        <groupId>org.apache.synapse</groupId>
        <artifactId>synapse-core</artifactId>
      </dependency>        
    </dependencies>
  • assemble-connector.xml - Contains the instructions to create the connector archive (ZIP) file.
  • connector.xml - Defines the connector name, package, and the different categories of operations that will be exposed for the connector. For example, the JIRA connector's connector.xml file looks like this:

    <connector>
        <component name="jira" package="org.wso2.carbon.connectors">
            <dependency component="jira_config" />
            <dependency component="jira_dashboard"/>
            <dependency component="jira_filter"/>
            <dependency component="jira_group"/>
            <dependency component="jira_issue" />
            <dependency component="jira_project" />
            <dependency component="jira_search" />
            <dependency component="jira_user" />
            <description>JIRA 6.0 connector</description>
        </component>
    </connector>

    For each of the categories you specify, you create a corresponding directory (as shown above in the directory tree), each of which contains a component.xml file.

  • component.xml - Contains information about the operations in this category. For example, in the jira_filter directory, the component.xml file looks like this:

    <component name="jira_filter" type="synapse/template">
        <subComponents>
            <component name="createFilter">
                <file>createFilter.xml</file>
                <description>Creates a new filter, and returns newly 
    created filter. Currently sets permissions just using the users default 
    sharing permissions</description>
            </component>
            <component name="deleteFilter">
                <file>deleteFilter.xml</file>
                <description>Delete a filter.</description>
            </component>
            <component name="getFavouriteFilters">
                <file>getFavouriteFilters.xml</file>
                <description>Returns the favourite filters of the logged-in user.</description>
            </component>
            <component name="getFilterById">
                <file>getFilterById.xml</file>
                <description>Returns a filter given an id</description>
            </component>
            <component name="updateFilterById">
                <file>updateFilterById.xml</file>
                <description>Updates an existing filter, and returns its new value.</description>
            </component>
        </subComponents>
    </component>

    Each operation is specified as a separate sub-component of the operation group.

  • <operation-name>.xml - Contains the actual API calling configuration. This file contains the steps necessary to call the API exposed by the service. For example, the createFilter operation defined above points to the file createFilter.xml, which uses templates to define the configuration:

    <template xmlns="http://ws.apache.org/ns/synapse" name="createFilter">
    <!-- actual configuration used to call the REST API -->
      <sequence>
        <property name="messageType" value="application/json" scope="axis2"/>
        <property name="Accept-Encoding" action="remove" scope="transport"/>
    <!-- calling the REST API through the call mediator -->
        <call>
          <endpoint>
            <http method="POST" uri-template="{uri.var.jira.url}/rest/api/2/filter"/>
          </endpoint>
        </call>
      </sequence>
    </template>

 

  • No labels