WSO2 ESB Connectors

The connectors listed in this section are 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.

A WSO2 connector allows you to interact with the functionality and data of a third-party product from your WSO2 ESB message flow. Thus it enables you to connect to and interact with the APIs of services such as Twitter, Salesforce, JIRA etc. For example, if you have enabled the Twitter and Google Spreadsheet connectors in your ESB instance, your message flow can receive requests containing a user's Twitter name and password, log into the user's Twitter account, get a list of the user's followers, and write that information to a Google spreadsheet. You can use one or more connectors in order to manage generic use cases related to a business scenario that you may need to address.

Each connector provides a set of operations , which you call from your proxy services, sequences, and APIs to interact with that product. For example, the Twitter connector provides operations that call the Twitter APIs to get and send direct messages, retrieve IDs of friends and followers, update status, retweet other users' status, and more. If you want your configuration to send a direct message to a Twitter user, you could call the twitter.sendDirectMessage operation and pass in the Twitter user's ID and the direct message text.

Types of Connectors

WSO2 ESB connectors are components that encapsulate third-party API calls.

Before you start writing a connector, you need to research the APIs provided by the service for which you want to write the connector. For example, if you are writing a connector for JIRA, you will see that 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 can create XML configuration files that define your connector and point to your Java classes that define the operations.

This section describes the different types of connectors in detail so that you can decide on the API you are going to use to write the connector.

SOAP-based connectors

If you are writing a SOAP API based connector, you can write the entire connector with Synapse configurations. You can create a maven project in your preferred IDE with a directory structure as described in Creating the Maven project template.

Following is an example of a SOAP-based connector that is written for Salesforce to execute the query method of the API:

<templatename="query"xmlns="http://ws.apache.org/ns/synapse">
 <parametername="sessionId"/>
 <parametername="url"/>
 <parametername="queryString"/>
 <sequence>
  <payloadFactory>
   <format>
    <soapenv:Envelopexmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"xmlns:urn="urn:partner.soap.sforce.com">
     <soapenv:Header>
      <urn:SessionHeader>
       <urn:sessionId>$1</urn:sessionId>
      </urn:SessionHeader>
     </soapenv:Header>
     <soapenv:Body>
      <urn:query>
       <urn:queryString>$2</urn:queryString>
      </urn:query>
     </soapenv:Body>
    </soapenv:Envelope>
   </format>
   <args>
    <argexpression="$func:sessionId"/>
    <argexpression="$func:queryString"/>
   </args>
  </payloadFactory>
  <propertyname="messageType"scope="axis2"value="text/xml"/>
  <headername="Action"value="urn:partner.soap.sforce.com/Soap/queryRequest"/>
  <propertyvalue="true"name="FORCE_ERROR_ON_SOAP_FAULT"/>
  <propertyname="HTTP_METHOD"scope="axis2"value="POST"/>
  <headername="To"expression="$func:url"/>
  <call>
   <endpoint>
    <defaultformat="soap11">
     <timeout>
      <duration>60000</duration>
      <responseAction>fault</responseAction>
     </timeout>
     <suspendOnFailure>
      <initialDuration>2000</initialDuration>
      <progressionFactor>1.0</progressionFactor>
      <maximumDuration>3000</maximumDuration>
     </suspendOnFailure>
    </default>
   </endpoint>
  </call>   
 </sequence>
</template>

Here the required payload is created using the PayloadFactory Mediator and the request is sent using the Call Mediator.

REST-based connectors

You can write a REST-based connector in a manner very much similar to how you write a SOAP-based connector. The only difference is the underlying communication mechanism. You can basically write a REST-based connector by using synapse configurations similar to SOAP-based connector.

Following is an example of a SOAP-based connector calling the Twitter rest API:

<template xmlns = "http://ws.apache.org/ns/synapse" name = "search">
  <parameter name = "search"/>
  <parameter name = "accessToken"/>
   <sequence>
    <property name = "uri.var.twitter.search" expression = "$func:search"/>
    <property name = "Authorization" expression = "$func:accessToken" scope = "transport"/>
    <property name = "messageType" value = "application/x-www-form-urlencoded" scope = "axis2"/>
    <payloadFactory media-type = "xml">
     <format >
      <soapenv:Envelope 
                  xmlns:soapenv
                 = "http://schemas.xmlsoap.org/soap/envelope/">
       <soapenv:Header/>
       <soapenv:Body/>
      </soapenv:Envelope>
     </format>
     <args/>
    </payloadFactory>
   <call>
    <endpoint>
     <http method = "GET" uri-template = "https://api.twitter.com/1.1/search/tweets.json?q={uri.var.twitter.search}"/>
    </endpoint>
   </call>
  </sequence>
</template>

Java API-based connectors

If you are writing a Java API-based connector, you have to use a custom class mediator to implement it. You need to extend the AbstractConnector class and implement its connect method. All the required logic must be done within this method. Once you have implemented this method, you can call the method using the synapse configuration, which is in the .xml file.

Following is an example of a connector Java class written for Twilio to send an SMS:

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

import org.apache.axiom.om.OMElement;
import org.apache.synapse.MessageContext;
import org.apache.synapse.SynapseException;
import org.apache.synapse.SynapseLog;

import org.wso2.carbon.connector.core.AbstractConnector;
import org.wso2.carbon.connector.core.util.ConnectorUtils;
import org.wso2.carbon.connector.twilio.util.TwilioUtil;

import com.twilio.sdk.TwilioRestClient;
import com.twilio.sdk.resource.factory.SmsFactory;
import com.twilio.sdk.resource.instance.Sms;

public class SendSms extends AbstractConnector {
    public void connect(MessageContext messageContext) {

        SynapseLog log = getLog(messageContext);
        log.auditLog("Start: send SMS");

        String to = (String) ConnectorUtils.lookupTemplateParamater(messageContext, TwilioUtil.PARAM_TO);
        String from = (String) ConnectorUtils.lookupTemplateParamater(messageContext, TwilioUtil.PARAM_FROM);
        String body = (String) ConnectorUtils.lookupTemplateParamater(messageContext, TwilioUtil.PARAM_BODY);
        String statusCallBackUrl = (String) ConnectorUtils.lookupTemplateParamater(messageContext,
                TwilioUtil.PARAM_STATUS_CALLBACK_URL);
        String applicationSid = (String) ConnectorUtils.lookupTemplateParamater(messageContext,
                TwilioUtil.PARAM_APPLICATION_SID);
        Map<string, string> params = new HashMap<string, string>();

        params.put(TwilioUtil.TWILIO_TO, to);
        params.put(TwilioUtil.TWILIO_FROM, from);
        params.put(TwilioUtil.TWILIO_BODY, body);

        if (applicationSid != null) {
            params.put(TwilioUtil.TWILIO_APPLICATION_SID, applicationSid);
        }
        if (statusCallBackUrl != null) {
            params.put(TwilioUtil.TWILIO_STATUS_CALLBACK, statusCallBackUrl);
        }

        try {
            TwilioRestClient twilioRestClient = TwilioUtil.getTwilioRestClient(messageContext);
            SmsFactory messageFactory = twilioRestClient.getAccount().getSmsFactory();
            Sms message = messageFactory.create(params);
            OMElement omResponse = TwilioUtil.parseResponse("sms.create.success");

            TwilioUtil.addElement(omResponse, TwilioUtil.PARAM_MESSAGE_SID, message.getSid());
            TwilioUtil.addElement(omResponse, TwilioUtil.PARAM_STATUS, message.getStatus());
            TwilioUtil.preparePayload(messageContext, omResponse);
        } catch (Exception e) {
            log.error(e.getMessage());

            messageContext.setProperty(SynapseConstants.ERROR_EXCEPTION, e);
            messageContext.setProperty(SynapseConstants.ERROR_MESSAGE, e.getMessage());
            messageContext.setProperty(SynapseConstants.ERROR_CODE, "0007");

            throw new SynapseException(e);
        }

        log.auditLog("End: send SMS");
    }
}

Following is the associated sendSms.xml that calls the class mediator:

<template name = "sendSms" xmlns = "http://ws.apache.org/ns/synapse">
  <parameter name = "body"/>
  <parameter name = "to"/>
  <parameter name = "from"/>
  <parameter name = "statusCallBackUrl"/>
  <parameter name = "applicationSid"/>
  <sequence>
   <class name = "org.wso2.carbon.connector.twilio.sms.SendSms"/>
  </sequence>
</template>

Now that you understand the possible types of connectors, you can decide on the API you are going to use to write the connector. The complete list of WSO2 ESB connectors is as follows: