Difference between revisions of "Custom SMS MMS Implementation"

(Implementation)
 
(8 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
== Introduction ==
 
== Introduction ==
 +
 +
  
 
Open-Xchange comes with an already integrated SMS/MMS UI Plugin, which enables OX endusers to send out SMS/MMS from within their browser.  
 
Open-Xchange comes with an already integrated SMS/MMS UI Plugin, which enables OX endusers to send out SMS/MMS from within their browser.  
  
 
IMPORTANT:
 
IMPORTANT:
Due to the fact, that there are many telecommunication companies out there which provide SMS/MMS gateways, you need to implement the process of sending out SMS/MMS within the OX backend for yourself or you can order and pay for this implementation work, so our developers will do the work for you.(Includes building rm/deb packages).
+
Due to the fact, that there are many telecommunication companies out there which provide SMS/MMS gateways, you need to implement the process of sending out SMS/MMS within the OX backend for yourself or you can order and pay for this implementation work, so our developers will do the work for you. (Includes building RPM/DEB packages).
  
 
Short summary of needed steps to make SMS/MMS messaging work:
 
Short summary of needed steps to make SMS/MMS messaging work:
Line 15: Line 17:
  
 
WARNING: If you do not implement the server side OSGI interfaces, you will not see any SMS/MMS functionality/window/button in the OX UI!!
 
WARNING: If you do not implement the server side OSGI interfaces, you will not see any SMS/MMS functionality/window/button in the OX UI!!
 +
 +
{|
 +
|[[File:Sms_1.png|290px|thumb|left|SMS Button]]
 +
|[[File:Sms_2.png|290px|thumb|left|SMS MMS New Window]]
 +
|[[File:Sms_3.png|290px|thumb|left|SMS MMS attachment]]
 +
|}
 +
  
 
== Prerequisites ==
 
== Prerequisites ==
Line 20: Line 29:
 
The bundles open-xchange-messaging-sms and open-xchange-messaging-sms-gui must be installed to use the SMS/MMS feature.
 
The bundles open-xchange-messaging-sms and open-xchange-messaging-sms-gui must be installed to use the SMS/MMS feature.
  
{{InstallPlugin|pluginname=open-xchange-messaging-sms open-xchange-messaging-sms-gui|sopath=stable}}
+
{{InstallPlugin|pluginname=open-xchange-messaging-sms open-xchange-messaging-sms-gui|sopath=updates}}
 +
 
 +
{{InstallPlugin|pluginname=open-xchange-messaging-sms|sopath=6.22/updates/backend|version=v6.22.x}}
 +
{{InstallPlugin|pluginname=open-xchange-messaging-sms-gui|sopath=6.22/updates/frontend|version=v6.22.x}}
  
 
== Implementation ==
 
== Implementation ==
  
The basic implementation must be done by a class implementing the interface <code>com.openexchange.messaging.sms.service.MessagingNewService</code>. This implementing class must be annouced to OSGi as a service implementation for this class. This can be done be the following:
+
The basic implementation must be done by a class implementing the interface [http://software.open-xchange.com/OX6/doc/sms/com/openexchange/messaging/sms/service/MessagingNewService.html <code>com.openexchange.messaging.sms.service.MessagingNewService</code>]. This implementing class must be annouced to OSGi as a service implementation for this class. This can be done be the following:
  
 
  context.registerService(MessagingNewService.class.getName(), new OwnImpl(), null);
 
  context.registerService(MessagingNewService.class.getName(), new OwnImpl(), null);
  
In this example the new class <code>OwnImpl</code> must be written. Inside this class the interface enforces that an object of the type <code>MessagingUserConfigurationInterface</code> and an object of the type <code>MessagingAccountTransport</code> must be returned in the corresponding methods.
+
In this example the new class <code>OwnImpl</code> must be written. Inside this class the interface enforces that an object of the type [http://software.open-xchange.com/OX6/doc/sms/com/openexchange/messaging/sms/service/MessagingUserConfigurationInterface.html <code>MessagingUserConfigurationInterface</code>] and an object of the type [http://software.open-xchange.com/OX6/doc/sms/com/openexchange/messaging/MessagingAccountTransport.html <code>MessagingAccountTransport</code>] must be returned in the corresponding methods.
  
Please note that each of the returned objects is only valid for one session. So the returned <code>MessagingUserConfigurationInterface</code> can provide user specific settings based on the values in the session object.
+
Please note that each of the returned objects is only valid for one session. So the returned [http://software.open-xchange.com/OX6/doc/sms/com/openexchange/messaging/sms/service/MessagingUserConfigurationInterface.html <code>MessagingUserConfigurationInterface</code>] can provide user specific settings based on the values in the session object.
The settings which can be adjusted in the configuration should be explained by the JavaDoc Links below.
+
The settings which can be adjusted in the configuration should be explained by the JavaDoc links.
  
The more important part is the returned <code>MessagingAccountTransport</code> where the method com.openexchange.messaging.MessagingAccountTransport.transport(MessagingMessage, Collection<MessagingAddressHeader>) is responsible for sending the SMS / MMS. The corresponding <code>MessagingMessage</code> object therefore provides all the needed data for composing the messages. The same applies for the <code>Collection<MessagingAddressHeader></code> is irrelevant in this case
+
The more important part is the returned [http://software.open-xchange.com/OX6/doc/sms/com/openexchange/messaging/MessagingAccountTransport.html <code>MessagingAccountTransport</code>] where the method [http://software.open-xchange.com/OX6/doc/sms/com/openexchange/messaging/MessagingAccountTransport.html#transport(com.openexchange.messaging.MessagingMessage,%20java.util.Collection) <code>com.openexchange.messaging.MessagingAccountTransport.transport(MessagingMessage, Collection<MessagingAddressHeader>)</code>] is responsible for sending the SMS / MMS. The corresponding [http://software.open-xchange.com/OX6/doc/sms/com/openexchange/messaging/MessagingMessage.html <code>MessagingMessage</code>] object therefore provides all the needed data for composing the messages. <code>Collection<MessagingAddressHeader></code> is irrelevant in this case
  
 
Please pay attention to the way how the sender and the receiver are fetched from the message object as this might be uncommon. The correct way to do it is:
 
Please pay attention to the way how the sender and the receiver are fetched from the message object as this might be uncommon. The correct way to do it is:
Line 40: Line 52:
 
  final MessagingHeader from = message.getFirstHeader(MessagingHeader.KnownHeader.FROM.toString());
 
  final MessagingHeader from = message.getFirstHeader(MessagingHeader.KnownHeader.FROM.toString());
  
The plain string is available through the <code>getValue()</code> method on the <code>MessagingHeader</code>
+
The plain string is available through the [http://software.open-xchange.com/OX6/doc/sms/com/openexchange/messaging/MessagingHeader.html#getValue() <code>getValue()</code>] method on the [http://software.open-xchange.com/OX6/doc/sms/com/openexchange/messaging/MessagingHeader.html <code>MessagingHeader</code>]
  
 
== JavaDoc ==
 
== JavaDoc ==
  
A JavaDoc of the described classes can be found [http://software.open-xchange.com/OX6/doc/sms/ here]
+
A full JavaDoc of the described classes can be found [http://software.open-xchange.com/OX6/doc/sms/ here]

Latest revision as of 08:29, 12 November 2012

Introduction

Open-Xchange comes with an already integrated SMS/MMS UI Plugin, which enables OX endusers to send out SMS/MMS from within their browser.

IMPORTANT: Due to the fact, that there are many telecommunication companies out there which provide SMS/MMS gateways, you need to implement the process of sending out SMS/MMS within the OX backend for yourself or you can order and pay for this implementation work, so our developers will do the work for you. (Includes building RPM/DEB packages).

Short summary of needed steps to make SMS/MMS messaging work:

1. Install needed packages (see below)


2. Implement the required OSGI interfaces (see below) and build a package/jar, which must be installed correctly on the OX server(s).


WARNING: If you do not implement the server side OSGI interfaces, you will not see any SMS/MMS functionality/window/button in the OX UI!!

SMS Button
SMS MMS New Window
SMS MMS attachment


Prerequisites

The bundles open-xchange-messaging-sms and open-xchange-messaging-sms-gui must be installed to use the SMS/MMS feature.

Install on OX AppSuite

Debian GNU/Linux 10.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/updates/DebianBuster/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/updates/updates/DebianBuster/ /

and run

$ apt-get update
$ apt-get install open-xchange-messaging-sms open-xchange-messaging-sms-gui

Debian GNU/Linux 11.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/updates/DebianBullseye/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/updates/updates/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install open-xchange-messaging-sms open-xchange-messaging-sms-gui


Install on OX v6.22.x

Debian GNU/Linux 10.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/6.22/updates/backend/DebianBuster/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/6.22/updates/backend/updates/DebianBuster/ /

and run

$ apt-get update
$ apt-get install open-xchange-messaging-sms

Debian GNU/Linux 11.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/6.22/updates/backend/DebianBullseye/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/6.22/updates/backend/updates/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install open-xchange-messaging-sms


Install on OX v6.22.x

Debian GNU/Linux 10.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/6.22/updates/frontend/DebianBuster/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/6.22/updates/frontend/updates/DebianBuster/ /

and run

$ apt-get update
$ apt-get install open-xchange-messaging-sms-gui

Debian GNU/Linux 11.0

Add the following entry to /etc/apt/sources.list.d/open-xchange.list if not already present:

deb https://software.open-xchange.com/products/6.22/updates/frontend/DebianBullseye/ /
# if you have a valid maintenance subscription, please uncomment the 
# following and add the ldb account data to the url so that the most recent
# packages get installed
# deb https://[CUSTOMERID:PASSWORD]@software.open-xchange.com/products/6.22/updates/frontend/updates/DebianBullseye/ /

and run

$ apt-get update
$ apt-get install open-xchange-messaging-sms-gui


Implementation

The basic implementation must be done by a class implementing the interface com.openexchange.messaging.sms.service.MessagingNewService. This implementing class must be annouced to OSGi as a service implementation for this class. This can be done be the following:

context.registerService(MessagingNewService.class.getName(), new OwnImpl(), null);

In this example the new class OwnImpl must be written. Inside this class the interface enforces that an object of the type MessagingUserConfigurationInterface and an object of the type MessagingAccountTransport must be returned in the corresponding methods.

Please note that each of the returned objects is only valid for one session. So the returned MessagingUserConfigurationInterface can provide user specific settings based on the values in the session object. The settings which can be adjusted in the configuration should be explained by the JavaDoc links.

The more important part is the returned MessagingAccountTransport where the method com.openexchange.messaging.MessagingAccountTransport.transport(MessagingMessage, Collection<MessagingAddressHeader>) is responsible for sending the SMS / MMS. The corresponding MessagingMessage object therefore provides all the needed data for composing the messages. Collection<MessagingAddressHeader> is irrelevant in this case

Please pay attention to the way how the sender and the receiver are fetched from the message object as this might be uncommon. The correct way to do it is:

final MessagingHeader to = message.getFirstHeader(MessagingHeader.KnownHeader.TO.toString());
final MessagingHeader from = message.getFirstHeader(MessagingHeader.KnownHeader.FROM.toString());

The plain string is available through the getValue() method on the MessagingHeader

JavaDoc

A full JavaDoc of the described classes can be found here