SMPP Connector Example¶

SMPP (Short Message Peer-to-Peer Protocol) Connector allows you to send an SMS from an integration sequence. It uses the jsmpp API to communicate with an SMSC (Short Message Service Center), which is used to store, forward, convert, and deliver Short Message Service (SMS) messages. jsmpp is a Java implementation of the SMPP protocol.

What you'll build¶

Given below is a sample scenario that demonstrates how to work with the WSO2 SMPP Connector and send SMS messages via the SMPP protocol.

The SMPP server in SMSC have all the ESME (External Short Messaging Entity) addresses. This is an external application that connects to a SMSC and the active connection. When you send an SMS to a destination, it comes to the SMSC. Then one of the modules in SMSC checks if the destination address is available or not. If it is available, it creates a connection object that is responsible for sending the SMS message. There are many SMPP gateways available in the world and now almost all the message centers support SMPP. It is not practical always to connect with real SMSC. However, in this scenario we will try it with SMSC simulator. Please refer the Setting up the SMPP Connector documentation.

The following sendSMSoperation is exposed via an API. The API with the context /send has one resource.

/send : Used to send SMS Message to the Short Message Service Center.

The following diagram shows the overall solution. There is an HTTP API that you can invoke with an HTTP call with JSON. The API is able to send a SMS for the request number in a JSON request with the message in JSON.

smpp connector example

If you do not want to configure this yourself, you can simply get the project and run it.

Configure the connector in WSO2 Integration Studio¶

Connectors can be added to integration flows in WSO2 Integration Studio. Once added, the operations of the connector can be dragged onto your canvas and added to your resources.

Import the connector¶

Follow these steps to set up the ESB Solution Project and the Connector Exporter Project.

Open WSO2 Integration Studio and create an Integration Project.
Right-click the project that you created and click on Add or Remove Connector -> Add Connector. You will get directed to the WSO2 Connector Store.
Search for the specific connector required for your integration scenario and download it to the workspace.
Click Finish, and your Integration Project is ready. The downloaded connector is displayed on the side palette with its operations.
You can drag and drop the operations to the design canvas and build your integration logic.
Right click on the created Integration Project and select New -> Rest API to create the REST API.

Add integration logic¶

First create an API, which will be where we configure the integration logic. Right click on the created Integration Project and select, New -> Rest API to create the REST API. Specify the API name as SmppTestApi and API context as /send.

Adding a Rest API

Configuring the API¶

Create a resource to send an SMS to the Short Message Service Center.

Set up the sendSMS operation.
1. Navigate into the Palette pane and select the graphical operations icons listed under SMPP Connector section. Then drag and drop the sendSMS operation into the Design pane.
2. Go to property values of sendSMS and click the + sign to create a new SMSC Connection. Replace the host, port, systemId, password with your values. You can reuse the SMSC connection among other operators.
  - host : IP address of the SMSC.
  - port : Port to access the SMSC.
  - systemId : username to access the SMSC.
  - password : password to access the SMSC.
  - systemType [Optional] : It is used to categorize the type of ESME that is binding to the SMSC. Examples include “CP” (Content providers), “VMS” (voice mail system) and “OTA” (over-the-air activation system).
  - addressTon [Optional] : Indicates Type of Number of the ESME address.
  - addressNpi [Optional] : Numbering Plan Indicator for ESME address.
3. In this operation we are going to send a SMS messages peer to peer using SMPP protocol. It provides a flexible data communications interface for transfer of short message data between a Message Centers, such as a Short Message Service Centre (SMSC), GSM Unstructured Supplementary Services Data (USSD) Server or other type of Message Center and a SMS application system, such as a WAP Proxy Server, EMail Gateway or other Messaging Gateway. Please find the mandatory send operation parameters listed here.
  - sourceAddress : Source address of the SMS message.
  - destinationAddress : Destination address of the SMS message.
  - message : Content of the SMS message.
  While invoking the API, the above three parameters values come as a user input.
4. To get the input values in to the API we can use the property mediator. Navigate into the Palette pane and select the graphical mediators icons listed under Mediators section. Then drag and drop the Property mediators into the Design pane as shown bellow.
  
  The parameters available for configuring the Property mediator are as follows:
  
  Note: That the properties should be add to the pallet before create the operation.
5. Add the property mediator to capture the sourceAddress value. The sourceAddress contains Source address of the SMS message.
  - name : sourceAddress
  - expression : json-eval($.sourceAddress)
6. Add the property mediator to capture the message values. The message contains content of the SMS message.
  - name : message
  - expression : json-eval($.message)
7. Add the property mediator to capture the destinationAddress values. The message contains content of the SMS message.
  - name : destinationAddress
  - expression : json-eval($.destinationAddress)
Get a response from the user.

When you are invoking the created API, the request of the message is going through the /send resource. Finally, it is passed to the Respond mediator. The Respond Mediator stops the processing on the current message and sends the message back to the client as a response.
1. Drag and drop respond mediator to the Design view.
1. Once you have setup the sequences and API, you can see the salesforcerest API as shown below.
Note: The properties should be added to the pallet before creating the operation.

Now you can switch into the Source view and check the XML configuration files of the created API and sequences.

SmppTestApi.xml

<?xml version="1.0" encoding="UTF-8"?>
<api context="/send" name="SmppTestApi" xmlns="http://ws.apache.org/ns/synapse">
    <resource methods="POST">
        <inSequence>
            <property expression="json-eval($.destinationAddress)" name="destinationAddress" scope="default" type="STRING"/>
            <property expression="json-eval($.message)" name="message" scope="default" type="STRING"/>
            <property expression="json-eval($.sourceAddress)" name="sourceAddress" scope="default" type="STRING"/>
            <SMPP.sendSMS configKey="SMSC_CONFIG_1">
                <sourceAddress>{$ctx:sourceAddress}</sourceAddress>
                <destinationAddress>{$ctx:distinationAddress}</destinationAddress>
                <message>{$ctx:message}</message>
            </SMPP.sendSMS>
            <log level="full">
                <property name="Message delivered sucessfully" value="Message delivered sucessfully"/>
            </log>
            <respond/>
        </inSequence>
        <outSequence/>
        <faultSequence/>
    </resource>
</api>

SMSC_CONFIG_1.xml

<?xml version="1.0" encoding="UTF-8"?>
<localEntry key="SMSC_CONFIG_1" xmlns="http://ws.apache.org/ns/synapse">
    <SMPP.init>
        <systemId>kasun</systemId>
        <connectionType>init</connectionType>
        <addressTon>INTERNATIONAL</addressTon>
        <password>kasun</password>
        <port>10003</port>
        <host>localhost</host>
        <systemType>SMS1009</systemType>
        <name>SMSC_CONFIG_1</name>
        <addressNpi>ISDN</addressNpi>
    </SMPP.init>
</localEntry>

Get the project¶

You can download the ZIP file and extract the contents to get the project code.

Tip

You may need to update the simulator details and make other such changes before deploying and running this project.

Deployment¶

Follow these steps to deploy the exported CApp in the integration runtime.

Deploying on Micro Integrator

You can copy the composite application to the <PRODUCT-HOME>/repository/deployment/server/carbonapps folder and start the server. Micro Integrator will be started and the composite application will be deployed.

You can further refer the application deployed through the CLI tool. See the instructions on managing integrations from the CLI.

Click here for instructions on deploying on WSO2 Enterprise Integrator 6

You can copy the composite application to the <PRODUCT-HOME>/repository/deployment/server/carbonapps folder and start the server.
WSO2 EI server starts and you can login to the Management Console https://localhost:9443/carbon/ URL. Provide login credentials. The default credentials will be admin/admin.
You can see that the API is deployed under the API section.

Testing¶

Invoke the API as shown below using the curl command. Curl Application can be downloaded from here.

Sample request

curl -v POST -d '{"sourceAddress":"16111", "message":"Hi! This is the first test SMS message.","distinationAddress":"071XXXXXXX"}' "http://172.17.0.1:8290/send" -H "Content-Type:application/json"

You will receive the messageId as expected response

{"messageId":"Smsc2001"}

Expected Response in SMSC simulator console

06:33:09 [sys] new connection accepted
06:33:09 [] client request: (bindreq: (pdu: 40 2 0 1) kasun kasun SMS1009 52 (addrrang: 1 1 ) ) 
06:33:09 [kasun] authenticated kasun
06:33:09 [kasun] server response: (bindresp: (pdu: 0 80000002 0 1) Smsc Simulator) 
06:33:09 [kasun] client request: (submit: (pdu: 106 4 0 2) (addr: 1 1 16111)  (addr: 1 1 071XXXXXXX)  (sm: msg: Hi! This is the first test SMS message.)  (opt: ) ) 
06:33:09 [kasun] putting message into message store
06:33:09 [kasun] server response: (submit_resp: (pdu: 0 80000004 0 2) Smsc2001 ) 
06:33:59 [kasun] client request: (enquirelink: (pdu: 16 15 0 3) ) 
06:33:59 [kasun] server response: (enquirelink_resp: (pdu: 0 80000015 0 3) ) 
06:34:49 [kasun] client request: (enquirelink: (pdu: 16 15 0 4) ) 
06:34:49 [kasun] server response: (enquirelink_resp: (pdu: 0 80000015 0 4) )