As we know, WSO2 and its products have many features and facilities for integration purposes. Today we’ll discuss connectors, another of these functions.
Connectors are encapsulated components that can contain multiple operations. Each of these operations enables us to connect to third-party APIs in various ways.
We are able to distinguish between the various types of connectors available based on our usual means of communication:
- Java: Performs operations via custom class mediators.
- SOAP Performs operations via SOAP calls.
- REST: Performs operations via REST calls.
As is customary, WSO2 has an extensive list of ad hoc connectors for some of the world’s best known applications, such as Twitter and Facebook.
In this tutorial, we’ll learn how to create a REST connector, which will enable us to communicate with the Telegram instant messaging application.
Connector Creation
The basic structure of the connector can be created using a maven archetype. This structure will be made up of configuration files, templates that will create connections with third-party APIs, and Java classes (in the case of a Java connector).
Our connector will be called telegramConnector and its creation command will be as follows:
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.4 -DgroupId=org.wso2.carbon.connector -DartifactId=telegramConnector -Dversion=1.0.0 -DarchetypeRepository=http://maven.wso2.org/nexus/content/repositories/wso2-public/
Connector Components
Connectors have two distinct parts:
1) The configuration files that allow us to specify the various templates and how to access them
- <connector_home>/src/main/resources/connector.xm
This is the main configuration file. In this file we will specify the connector’s descriptive values, such as its name, description, and its dependencies or components.
<connector>
<component name="telegramConnector" package="org.wso2.carbon.connector">
<dependency component="message" />
<description>WSO2 telegramConnector connector library</description>
</component>
<icon>icon/icon-small.gif</icon>
</connector>
- <connector_home>/src/main/resources/config/component.xml
These components, which in turn can be divided into other subcomponents, are the operations that we will make available to users. We will also indicate the template associated with the operation in these components.
<component name="message" type="synapse/template" >
<subComponents>
<component name="message" >
<file>message_template.xml</file>
<description>telegram message method</description>
</component>
</subComponents>
</component>
In a simple connector we could have a single component, which, in turn, has a single associated operation.
However, when it comes to larger APIs, we are able to distinguish between these components based on the context of the API. Likewise, we can distinguish between subcomponents based on the API resources.
2) The templates which will contain the mode of communication with the external API
- Templates
These templates will be used by WSO2. Here, we will include the necessary logic to connect with the API. They are located in the following directory: <connector_home>/src/main/resources/config/
<template xmlns="http://ws.apache.org/ns/synapse" name="message">
<parameter name="text" />
<parameter name="chatId" />
<sequence>
<property name="uri.var.botApiToken" expression="wso2:vault-lookup('botApiToken')" scope="default" type="STRING"/>
<property name="uri.var.chatId" expression="$func:chatId" />
<property name="uri.var.msg" expression="$func:text" />
<call>
<endpoint>
<http method="post" uri-template="https://api.telegram.org/bot{uri.var.botApiToken}/sendMessage?chat_id={uri.var.chatId}&text={uri.var.msg}" />
</endpoint>
</call>
</sequence>
</template>
In this template we can see how to send a message to a Telegram chat. The main steps in enabling a chat and allowing us to send messages in it are as follows:
- Create a Telegram bot.
- Create a chat or public channel.
- Give the bot administrator permissions.
- Associate the bot identifier, the chat, and the message itself with the call to the Telegram API.
Connector Installation
Once we’ve designed all the necessary components, we must package our project using the following maven command:
| mvn package |
The next step will be to access the carbon management console and include the generated zip. In order to include the connector we must access the menu option Main > Connectors > Add. Enable the installed connector to complete the process.
Execution
The only thing left to do is to invoke the connector. For this purpose, we will create, for example, a proxy Service that will receive a message and send it to the Telegram chat in its input sequence.
<sequence name="basicSequence" xmlns="http://ws.apache.org/ns/synapse">
<property expression="$body/content" name="content"/>
<telegramConnector.message>
<chatId>@WSO2ConnectorExample</chatId>
<text>{$ctx:content}</text>
</telegramConnector.message>
<respond/>
</sequence>
As you can see, the connector is called ‘telegramConnector’ as indicated in the main configuration file. The operation that enables us to send the message is ‘message’ as we indicated in the component configuration file.
Conclusion
As you can see, a connector is another great tool that allows us to enable connections with other APIs, encapsulate all the code related to said connections, and reuse it easily.
