All docs This doc

Versions Compared

Key

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

...

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.

Table of Contents
maxLevel4
minLevel4

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:

Code Block
languagexml
linenumberstrue
<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:

Code Block
languagexml
linenumberstrue
<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:

Code Block
languagejava
linenumberstrue
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:

Code Block
languagexml
linenumberstrue
<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:

...