Revision as of 10:33, 16 December 2010 by Holgi (talk | contribs) (Introduction)

Upsell Layer


The Open-xchange Upsell packages provide the ability to show an Open-Xchange user which is using a free for charge package like "Webmail" or "PIM" advertisements.

When such a "freemail" user clicks on a feature like "Download Outlook Oxtender", "Enable Mobility" or wants to "Access Infostore" an Upsell Layer is shown where the user learns more about the missing functionality in form of text, screenshots and a video explaining the feature.

Based on the configuration the user can request a free trial of a package like "Premium Groupware" or / and can buy the package within the Upsell Dialogue with one simple click.

It is also possible for hosting companies to easily integrate their own online shop into the Open-Xchange Upsell Layer.

The customer never has to leave the application to upsell - it's a native IN APP upsell.

Upsell Layer Mobility
Upsell Layer Infostore
Upsell Layer Calendar

We have implemented 3 different types how to process the upsell an user is requesting in the hosters backend:

  • Show the Upsell Layer window and trigger the upgrade via a generated email to an email address after user clicked "buy" or "trial".

In this email there is the information which user from which contaxt wants to upgrade to which package. After receiving the email the hoster's sales team can put the customer into billing.

  • Show the Upsell Layer window and open a configurable URL including all needed parameters after the user clicked "buy" or "trial.

This is the perfect automated way if the hoster wants to have a full automated upsell which he can easily integrate into his existing provisioning & billing system.

  • Directly display a configurable URL/Online SHOP (systemwide or/and per context configurable) within the upsell Layer window instead of standard OX upsell content.

This is the perfect automated way for all hosters which have an online shop in place and wants to use it for the upsell, too.

The upsell layer has full i18n (EN and DE are included) support integrated and offers following components for advertisement:

  • Text
  • Video
  • Screenshots

to promote a certain feature for Open-Xchange.

The important part of the upsell layer is the ability to pass all needed parameters from users session like username,id,cid etc. + the feature he wants to buy, to a third party online shop system or send these parameters via email in machine readable (configurable) format to a dedicated mailsystem which can process it via procmail or similar to trigger the upgrade process via the Open-Xchange API´s (SOAP,RMI,CLT).


  • Download and install following OX upsell packages from the corresponding repository:

After installation of these packages, you have installed one server side plugin and one gui-plugin. If you have dedicated apaches running in your setup, only install the "open-xchange-upsell-multiple-gui" package on them. The upsell layer is now available to ALL contexts/users of this OX application server/gui instance. All UI plugin contents are installed under following directory (on Debian based installations):


It contains different subdirectories, for example:

css  - All colors, styles are defined within this directory.
lang - All translated PO files must be stored below this directory.
templates - If you want to change/replace screenshots, videos, layouts etc. check this directory.

The server side plugin comes with some templates, for example to change the advertisement text which is sent to the user, or the mail which is sent to the upgrade processing email system. All of them are stored below /opt/open-xchange/etc/groupware



Once installed, all nessecary configuration can be done in one single file. This file can be found at the following directory on the OX application server:


Switching between the 3 different types of the upsell layer, edit parameter:


Possible values: "direct", "static" or "email".

direct = Redirect within IFRAME immediately to parameter "com.openexchange.upsell.multiple.method.static.shop_redir_url" or to the context specific URL value after clicking one of the upsell triggers.

static = Redirect AFTER clicking a button within the shipped OX Upsell pages to parameter "com.openexchange.upsell.multiple.method.static.shop_redir_url" or to the context specific URL value after clicking one of the upsell triggers.

email = Send email to specific address AFTER clicking a button within the shipped OX Upsell pages

Defining the redirect URL for method "static" and "direct" for all contexts which are not specially provisioned, edit parameter:




As you can see from the example, the server side upsell plugin will replace all placeholders (_USER_ , _USERID_ etc.) with the data from the users OX session while he is logged into OX. You can use following parameters in this URL:

"_UPSELL_PLAN_" - Not in use.
"_PURCHASE_TYPE_" - Only used if email or static method is used due to the OX upsell layout/buttons
"_INVITE_" - User checked "invite my friends" checkbox in upsell box

If you need a different URL than specified in this configurtion for one or mor e OX Contexts, you must set the custom attribute:


into the admin user of the context via SOAP,RMI OR Commandline Tools.

WARNING: Due to Database restriction, you can only set the URL without any PAR AMETERS. PLEASE ONLY SET THE HOST+PATH to your WEBAPP.

Following PARAMETERS will be automatically appended to the URL:


To set the custom attribute via Commandline Tools, use following example:

changeuser -i 2 -c 424242667 --com.openexchange.upsell/url="http://my.reseller1.com/path/to/webapp/or/php_page.php?"

Defining the email address where upsell plugin will send all infos to for processing this request in a machine readable format:


The mail will be send to this email address. It should be processed by some script via procmail or similar to trigger an API call later on.

Email template to load for sending the machine readable mail, if not found, hardcoded text will be used:


All needed paramaters can be included in this email. You can use same placeholders as in the "REDIRECT URL", which is explained above.

Defining email subject to use when sending upsell request mails. See available placeholder above:


If you like, the upsell plugin can also send an info/advertisement email to ox enduser to inform about upsell after the machine readable mail was sent:


Defining email template to load for ox enduser, if mail to enduser is configured:


If you need i18n support within email templates, create template with suffix "_<LANGUAGE_CODE>" . Example: /var/upsell_mail_body_ox_enduser.tmpl_de_DE

If you want to use the builtin upgrade methods, you must also configure the OX RMI API informations:


Adding new feature (e.g. video, screenshot)

  • Open register.js (located in gui folder)
  • Search for upsell.config.features
  • add the following code ( description inline )
featurename: {
  name: ["trigger element"],
  title: _("upsell window title"),
  product_name: _("feature headline"),
  intro: _("upsell description text"),
  list: {
    list_item_1:  _("enumeration"),
    list_item_2:  _("enumeration"),
    list_item_3:  _("..."),
  outro: _("upsell text that shows at end"),
  videos: {
    video_1: {
      thumb: "name_of_video_thumbnail.png",
      video: "name_of_video_file.swf"
  images: {
    image_1: {
      thumb: "name_of_image_thumbnail.png",
      image: "name_of_lightbox_image.png"
  buttons: {
    trial: {
      content: _("buttonlabel"),
      action: "put javascript actions here if any"
  checkboxes: {
      content: _("checkboxlabel"),
      action: "put javascript actions here if any"
  • after the feature is implemented you should create the nessacarry files and place them as follow
---- language ( for example de_DE )
-------- flash ( for videos )
-------- img ( for images )

Load required js/cs files

  • to load additional files open register.js and add the following code
upsell = {
  files: {
    jss: {
      name: {
        script: "name.js",
   css: {
     name: "name.css",
  • add name.js to jss/name.js
  • add name.css to css/name.css

Change look and feel (e.g. branding, colors and sizes)

  • you should edit the existing css located in /var/www/ox6/plugins/com.openexchange.upsell.multiple.gui/css/upsell.css
  • you can add / edit background in /var/www/ox6/plugins/com.openexchange.upsell.multiple.gui//img

Possible triggers