AppSuite:OX Engage
Contents
Introduction
OX Engage is an Open-Xchange patented technology that enables the injection of messages into the email stream of any user using the Internet Message Access Protocol (IMAP) [Patent "Ad hoc injection of IMAP objects" (US 9531785 B1) see United States Patent or Google Patents].
These IMAP objects may appear in the inbox of a user on any IMAP capable device, and may feel like an email to the user, although the IMAP objects were never sent over a SMTP server or protocol.
Information that is stored in these IMAP objects can include advertising, promotions, service alerts or any other conceivable content of a regular email. When a mail client requests a list of emails for an IMAP user folder from the IMAP server, the IMAP server will ad-hoc inject IMAP objects into the customer’s inbox.
The rules that define the objects to be injected, the respective time schedule and target audience, as well as the position of the message in the user’s inbox are dependent on configurable object- and/or user profiles and other targeting parameters.
Components
- Integrated Campaign Management Platform (CMP) to create and schedule campaigns through a user interface.
- OX Mail Injection Middleware (MIM) to decouple the OX Dovecot Pro IMAP server from the CMP.
- OX Dovecot Pro IMAP Server (to be obtained separately) to fetch campaign templates and any user-specific variables provided by the Customer and to inject messages into the user’s IMAP stream.
- OX Monetization Database (MDB), only for OX Managed customers, to map userID to email address.
Please see OX Engage Product Guide for more information: http://software.open-xchange.com/products/ads/doc/OX_Engage_Product_Guide_1_1_0.pdf
Requirements
Please Note: OX Engage is only available for OX Dovecot Pro. Please contact Open-Xchange Sales for further information.
The following is required:
- A Linux operating system (without graphical user interface). Supported are: Debian 9 (Stretch), Red Hat Enterprise Linux 7, CentOS 7. Systemd is required as init system.
- OpenJDK JRE 8
- Cassandra >= 3.9 (Data storage; Tested with 3.11.1)
- AWS S3 compatible object store with at least support for Signature Version 2 (http://docs.aws.amazon.com/AmazonS3/latest/dev/auth-request-sig-v2.html)
- OX Dovecot Pro as an underlying IMAP server
Download and Installation
Decouples the OX Dovecot Pro IMAP server from the CMP
- mail-injection-middleware
Installation on the server varies depending on the underlying distribution, details are as follows.
Debian GNU/Linux 9.0
If not already done, add the following repositories to your Open-Xchange yum configuration:
deb https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/ads/stable/mail-injection-middleware/DebianStretch /
and run
$ apt-get update $ apt-get install mail-injection-middleware
Redhat Enterprise Linux 7
If not already done, add the following repositories to your Open-Xchange yum configuration:
[open-xchange-mail-injection-middleware] name=Open-Xchange-mail-injection-middleware baseurl=https://LDBUSER:LDBPASSWORD@software.open-xchange.com/products/ads/stable/mail-injection-middleware/RHEL7/ gpgkey=https://software.open-xchange.com/oxbuildkey.pub enabled=1 gpgcheck=1 metadata_expire=0m
and run
$ yum update $ yum install mail-injection-middleware
Cassandra
A Cassandra keyspace needs to be created where the MIM does create all necessary tables automatically then. Below example shows the CQL command to create a keyspace for development or basic testing purposes.
Important: You need to choose a strategy and replication factors depending on your physical Cassandra setup. In most cases this is probably 'NetworkTopologyStrategy' with replication factors >= 2 per data center. A proper replication configuration is crucial for mail injection decisions and the availability of mail contents.
CREATE KEYSPACE mim WITH replication = {'class': 'SimpleStrategy', 'replication_factor': '1'};
Server Configuration
Before the MIM daemon can be started for the first time, it must be basically configured.
Please Note: Configuration files are not merged automatically via post-install scripts. Administrators need to take of comparing their configurations with newer default file versions.
Process and Java Options
Process limits (ulimits) like number of child processes and number of open files must be configured via systemd, similar as described here: http://oxpedia.org/wiki/index.php?title=AppSuite:ResourceLimits.
JVM options can be configured in /opt/mail-injection-middleware/conf/mail-injection-middleware.conf. The most important property is the max. heap size the JVM may acquire via the Xmx option.
Application Properties
The application itself gets configured in /opt/mail-injection-middleware/conf/application.properties. Most mandatory options are set to reasonable defaults. Others like Cassandra connection properties and S3 access must be set manually.
# Cassandra # All possible properties can be found here: https://docs.spring.io/spring-boot/docs/1.5.4.RELEASE/reference/html/common-application-properties.html. Search for prefix "spring.data.cassandra". spring.data.cassandra.keyspace-name=mim spring.data.cassandra.contact-points=<cassandra-hosts> spring.data.cassandra.port=9042 spring.data.cassandra.schema-action=CREATE_IF_NOT_EXISTS
Start Service
$ systemctl start mail-injection-middleware.service
The MIM starts logging to /var/log/mail-injection-middleware/mail-injection-middleware.log shortly after starting the service. Start-up was successful if no ERROR messages with Java stacktraces appear in the log and the INFO message "Started MIMApplication in XX.XXX seconds (JVM running for XX.XXX)" was printed.
Tenant Management
OX Dovecot Pro Compatibility
To ensure Dovecot compatibility there has to be at a tenant with the ID "default". This tenant is used for every Dovecot request automatically as Dovecot doesn't provide tenantId's via URL.
Create new tenant
POST (url)/api/tenants/?createDB=true - This call will create a new keyspace and tables for the tenant in addition to the configuration data stored in keyspace "spring.data.cassandra.keyspace-name". In case createDB isn't set or set to false the keyspace and tables have to be present before the first usage of the tenant.
{"id":"default",
"name":"default",
"keyspaceName":"mim_default",
"configuration": {
"secretKey":"<secretKey>",
"hashedEmailAddresses": true/false
},
"conversionPoints": [{
"id":"injection",
"type": "ongage",
"eventType":"injected",
"description": "Dovecot Injection Tracking",
"connectionInformation": {
"url": "<injectionUrl>"
}
},{
"id":"reinjection",
"type": "ongage",
"eventType":"reinjected",
"description": "Dovecot Re-Injection Tracking",
"connectionInformation": {
"url": "<reinjectionUrl>"
}
},{
"id":"read",
"type": "ongage",
"eventType":"read",
"description": "Dovecot Read Tracking",
"connectionInformation": {
"url": "<readUrl>"
}
},{
"id":"expunged",
"type": "ongage",
"eventType":"expunged",
"description": "Dovecot Expunged Tracking",
"connectionInformation": {
"url": "<expungedUrl>"
}
}],
"dataSources": [{
"id":"default",
"type": "ongage",
"defaultDataSource": true,
"deleteTemporaryImportFiles":false,
"awsConnectionInformation": {
"authorizationType":"rados",
"accessKey":"<accessKey>",
"secretKey":"<secretKey>",
"endpoint":"<endpoint>",
"bucket":"<bucket>"
}
}]}
Delete tenant
DELETE (url)/api/tenants/(tenantId)/ - Deletes tenant configuration data stored in keyspace "spring.data.cassandra.keyspace-name". The keyspace related to this tenant will NOT be deleted.
DataSources
DataSources are used as import-sources. In most cases there has to be only one DataSource per tenant - this has to be marked as default (defaultDataSource = true). The first DataSource will be created during tenant creation.
List DataSources GET (url)/api/tenants/(tenantId)/dataSources
Change DataSources PUT (url)/api/tenants/(tenantId)/dataSources - Use the result of the list call, modify accordingly and provide the whole new list.
