OX Display deprecated
OX Display advertising plugins can be configured by making use of server-side configuration. For that, App Suite Middleware offers an administrative API to set the according configuration and App Suite UI can fetch and use that configuration through App Suite HTTP API.
Whether server-side configuration is an option, depends on the specific advertisement plugin.
Tenants and Packages
The server-side advertisement configuration has been designed in a way, that it supports multi-tenancy and multi-package setups.
Multi-tenancy: A single App Suite deployment that serves multiple isolated customers through the reseller plugin. In the following, the terms reseller, brand and tenant are interchangeable.
Multi-package: Different pricings/feature sets. Think of free and paid accounts with the latter having less or no advertisement, while the former are subject to advertisement revenue alone.
Installation and Configuration
As a first step, install the
open-xchange-advertisement package on all middleware nodes. Second, all nodes need to be equipped with a piece of configuration, that defines resellers/tenants, packages and the way to determine a user's package ("package scheme").
Configuration takes place in file
/opt/open-xchange/etc/advertisement.properties. Per default that file doesn't exist and server-side advertisement configuration is unavailable for all users. Configuration options are described here. Configuration changes can be applied without server restart with
Global Package Scheme
The global scheme is the default scheme. It assumes that there are no (or just one) reseller and just one package. It uses the value
default for both reseller and package.
Access Combination Package Scheme
This scheme uses access combination names as package names. The name is determined by the provisioned module accesses of the user, see
ModuleAccessDefinitions.properties. An example package name would be
groupware_premium, referring to all users within a tenant that have the according access combination set.
Taxonomy/Types Package Scheme
This scheme is based on context taxonomies. It requires a unique taxonomy/type per context, referring to the actual package. For example, each context tagged with
--taxonomy/types=freemail would be configured by storing an advertisement configuration for package
freemail of the according tenant.
Advertisement configuration per tenant and package can be set through an administrative API.
Without the reseller plugin installed, the reseller name is always
default. With package scheme
Global, the only available package is always
To support previewing configuration changes before making them effective for all users of a package, the API contains calls to set and delete the advertisement configuration for a certain user, based on its context ID and user ID. The idea behind that is, to create a preview user per package and tenant. Configuration changes would then in a first step be set for the according preview user alone. After verifying that the configuration works as expected, it can be rolled out to the whole package, using the respective API call.
This tool allows the master admin to remove the advertisement configurations. He can either remove all or a single reseller configurations. It is also possible to remove only the resellers, which are not active anymore (e.g in case they are deleted).
-A,--adminuser <arg> Admin username -c,--clean If set the clt only removes configurations of resellers which doesn't exist any more. -h,--help Prints a help text -i,--includePreviews If set the clt also removes preview configurations. This is only applicable in case the argument 'clean' is used. -P,--adminpass <arg> Admin password -p,--port <arg> The optional RMI port (default:1099) -r,--reseller <arg> Defines the reseller for which the configurations should be deleted. Use 'default' for the default reseller or in case no reseller are defined. If missing all configurations are deleted instead. --responsetimeout <arg> The optional response timeout in seconds when reading data from server (default: 0s; infinite) -s,--server <arg> The optional RMI server (default: localhost)
The configurations will be stored as JSON strings within ConfigDB in the table
advertisement_config. Additional there is another table with the name
advertisement_mapping which contains a mapping from a pair of reseller and package to an advertisement config. Here reseller references the name of the reseller and package references a package name. In case there is no reseller or in case of a single package, the entry can be replaced by the value
For example if you have no reseller and two packages with the names "packA" and "packB" you use "default" for the reseller and either "packA" or "packB" for the package. Which packages are available depends on the configuration of the middleware. Furmost it depends on which package scheme is configured.