= Open-Xchange Parallels Automation Deployment Guide =

This guide describes the integration of Parallels Automation with Open-Xchange.

== Terms and Abbreviations ==

;APS: Application Packaging Standard
;PBA: Parallels Business Automation.
;POA: Parallels Operations Automation.
;RST: Resource Type
;RS: Resource
;ST: Service Template
;Context: In Open-Xchange, a Context is a container for one or more users. Usually one Context contains one domain..

== Business Model Overview ==

== Customer’s Workflow ==

Numbered list of steps the customer follows to use Open-Xchange.

# Go to online store front and locate the Open-Xchange service.
# Add the plan/subscription for the Open-Xchange Service to your cart.
# On the checkout page review your order, accept the license agreement if any, then create a new customer account or login to an existing account to place your order.
# Login to your Customer control Panel using the login credentials created during the initial purchase.
# Select the appropriate subscription from the Subscription List on the Top of the Control Panel.
# Go to Applications, you will find the subscribed Application on the dashboard, where the Open-Xchange APS Package is available.
# Click on Open-Xchange APS application to start the installation.
# Click on Create and enter user details.
# Click next and confirm the fields are correct and press "Finish" to process.
# After the application provisioning process is completed it will have the status Ready.
# Click on Users to create some service users with access to Open-Xchange webmail.
# An auto login (Entry point) link will be displayed on their control panel using which the customer can login to Open-Xchange.

== Customer’s Lifecycle ==

Customers may make use of the service after acquiring a subscription from their Provider. In a typical setup, no resources are purchased up-front but are instead billed based on usage of mailboxes during consumption of these services.

=== Service Hierarchy Subscription Modification Options ===

* Main service
** User Registration
* Sub-services
** Entry point (Auto login) link to Open-Xchange Admin Account
** Entry points to link to Open-Xchange Webmail accounts
* Parallels Open-Xchange customer subscription management
** Through PBA storefront or subscription’s account details, user can purchase additional features or file storage
** No other service upgrades or downgrades offered

== Localization List ==

Supported translations of Open-Xchange as well as APS package translations of the customer interface are
listed on the [[Available_Translations|list of available translations]]

== Changelog ==

{{OXAPSChangelog|mode=poa}}

== Contractual contact information ==

=== Support Expectations ===

== Technical Integration Overview ==

This section contains an outline of how the integration of Open-Xchange and PA is performed and the list of Open-Xchange features that are supported within the integration package.

=== General Architecture ===

The following scheme represents the architecture of POA and Open-Xchange integration:

* Admin Level
** Download the Open-Xchange APS from APS catalog
** Install the APS package in POA
** Follow all steps to create resource types
** Fill all necessary Global settings
** Follow all steps to create Service templates
** Create plans in PBA
** Publish it to PA Store front

* End user Level:
** PA end user will come to Parallel automation Store front
** Select respective plan from the storefront
** Select the subscription period
** Create a new user or use existing user account
** Continue billing steps
** Once billing is done the application will be provisioned under the user using values from the global settings
** Login to customer account. Customer can see new subscription under available Open-Xchange subscription list
** Entry points (auto-login) will be generated by the APS package once the package is successfully provisioned

=== Services Summary ===

* The end user has to add mail hosting to the domain that should be used with Open-Xchange.
* The Open-Xchange APS package allows the end user to create a Context in Open-Xchange.
* Once the Context has been created, the user can create webmail accounts for Open-Xchange using existing or new service users.
* Entry points will be created for each webmail account and for the Open-Xchange Admin account.
* Depending on the billing configuration (storage based, account or functionality based), the user can be billed.

=== Object Mapping ===

Parallels Automation subscription corresponds to Context in Open-Xchange and Parallels Automation end users correspond to users in Open-Xchange.

== Requirements ==

The APS Package requires POA 5.0 or higher, Plesk 11.5 or higher and Open-Xchange 6.22.3 or higher / OX App Suite 7.2.1 or higher. Hence updating from e.g. 6.20.7 to 6.22.0 needs a further update to a required version as 6.22.0 doesn't work with APS package at all because 6.22.0 doesn't provide a proper authentication service which works with Parallels.

== Known issues ==

* Controlling module access combination names of created contexts results into "null". The reason is, that the aps package removes the editPassword right and thus, no existing access combination name exists per default, that match the individual settings.

== Download ==

=== APS package ===

Download the APS package from the [http://dev.apsstandard.org/apps/?name=Open-Xchange APS catalogue]

=== Open-Xchange ===

Simply follow the "''Hosting Edition deployment tutorials''" at [[Main_Page_HESE#quickinstall]] to install Open-Xchange Hosting Edition on your favorite Linux distribution, but make sure you install the packages below instead of the default OX meta/packages provided in the manual, because PA integration needs a different set of software:

'''Note:''' Stop before step "Creating contexts and users " - this is not necessary since all administration of contexts and users will be handled via PA.

Please install following packages on the OX server. These are mandatory for the PA integration:

<pre>
open-xchange-parallels
open-xchange-parallels-gui
open-xchange-spamhandler-spamassassin
open-xchange-admin-soap
</pre>

or

<pre>
open-xchange-meta-parallels
</pre>

'''Important:'''

Make sure that you don't have any other „spamhandler“ package installed like „open-xchange-spamhandler-default“. Also make sure, that you dont have any other OX authentication package installed like „open-xchange-authentication-database“. Additionally, don't install following packages, since they are not needed for POA installation:
<pre>
open-xchange-admin-plugin-contextrestore, open-xchange-log4j, open-xchange-passwordchange-database, open-xchange-passwordchange-servlet
</pre>
If already installed, please uninstall first!

These packages contain POA specific plugins for authentication, branding and advanced antispam cababilities. After you installed these packages via your favorite package manager like apt or yum, please restart the open-xchange server. To verify that the plugins are correctly loaded, please execute the command „listbundles“ which is located in /opt/open-xchange/sbin“. It should return a list with all „ACTIVE“ bundles.

If the bundle „com.openexchange.custom.parallels“ is not set to „ACTIVE“, please have a look at all OX logfiles located under „/var/log/open-xchange“ and watch out for error messages.

=== Installation of the Connector for Business Mobility ===

If you plan to sell Open-Xchange Business Mobility function (synchronisation with mobile phones) in combination with PA, you should also follow the official installation guide, which can be found also on the OXpedia website:

[[AppSuite:Connector_for_Business_Mobility_Installation_Guide|Connector for Business Mobility Installation]]

== Open-Xchange Configuration ==

=== SOAP ===

The PA system must be able to access at least one Open-Xchange server via SOAP. This can be configured via apache configuration.
When you followed our guides, that will be in the file <tt>/etc/apache2/conf.d/proxy_http.conf</tt> on Debian or <tt>/etc/httpd/conf.d/proxy_http.conf</tt>
in Redhat based systems. It might look like this

<Location /webservices>
# restrict access to the soap provisioning API
Order Deny,Allow
Deny from all
Allow from 127.0.0.1 192.168 172.16.1.2
</Location>

which would allow access to the SOAP provisioning on the network 192.168 and on the single hosts 127.0.0.1 and 172.16.1.2

=== Configuration of POA specific OX plugins ===

{{POAPleskConfig}}

a) To enable the OX-POA antispam functionality you must first edit file „/opt/open-xchange/etc/imap.properties“ and set property „com.openexchange.imap.spamHandler“ to value „SpamAssassin“.

<pre>
# Define the registration name of the appropriate spam handler to use
com.openexchange.imap.spamHandler=SpamAssassin
</pre>

Next you have to edit file „/opt/open-xchange/etc/spamassassin.properties“ and set property „com.openexchange.spamhandler.spamassassin.spamd“ to value „true“.

<pre>
# Choose if a mail should be send to spamd afterwards
com.openexchange.spamhandler.spamassassin.spamd=true
</pre>

 INFO:

 If POA XML-RPC Service runs on a different port than „3100“.

Please edit file:

"/opt/open-xchange/etc/parallels.properties"

and set property

"com.openexchange.custom.parallels.antispam.xmlrpc.port" to your custom port.

Make sure that the OX HOST IPs are added to "/etc/mail/spamassassin/allowed_ips" on the POA antispam/mail server. Else OX can not connect to POA spamassasin to learn new mails and you will get "connection reset" errors in open-xchange logfile.

2a) To configure POA antispam lists management via OX UI through POA-OpenAPI, you have to modify "/opt/open-xchange/etc/parallels.properties" and should adjust following parameters:

<pre>
#
## OpenAPI properties for managing Black&White Lists via OX GUI
#
# This property defines the URL to the HTTP OpenAPI interface of POA
com.openexchange.custom.parallels.openapi.interface_url=http://<coreserver>:<port>/

#
# This property defines if OpenAPI calls should be made with http basic auth
com.openexchange.custom.parallels.openapi.auth_enabled=false

#
# This property defines OpenAPI http basic auth credentials auth id
com.openexchange.custom.parallels.openapi.auth_id=openapi_user_id

#
# This property defines OpenAPI http basic auth credentials auth password
com.openexchange.custom.parallels.openapi.auth_password=openapi_password

#
# The property defines the mount point of the OX OpenAPI servlet implementation.
# Typically, no need to change it.
com.openexchange.custom.parallels.openapi_servlet=/ajax/parallels/openapi
</pre>

b) To enable correct branding for POA resellers and their customers, you have to define a „fallback“ FQDN under which the OX installation is reachable under the default skin/theme via http/https.  To achieve this, please edit file „/opt/open-change/etc/parallels.properties“ and set property „com.openexchange.custom.parallels.branding.fallbackurl“ to the approciate value of your OX installation.

<pre>
# THIS property below must only contain FQDN to OX GUI
# like webmail.system.com/ox6
com.openexchange.custom.parallels.branding.fallbackurl=ox.aps.sw.ru
</pre>

c)To enable correctly generated direct links when customer/context is branded you have to edit file „/opt/open-xchange/etc/notification.properties“ and set property
„object_link“ to value „http://[hostname]/#m=[module]&i=[object]&f=[folder]“

<pre>
object_link=http://[hostname]/#m=[module]&i=[object]&f=[folder]
</pre>

d) To support IDN Domains you also have to switch off username validation. To achieve this, please modify file "/opt/open-xchange/etc/AdminUser.properties" and update corresponding property:

<pre>
CHECK_USER_UID_FOR_NOT_ALLOWED_CHARS=false
</pre>

e) The Open-Xchange SOAP interface is used by POA to provision the OX system. To restrict access to this interface, we recommend that you add following lines to the apache2 configuration of OX (/etc/apache2/conf.d/ox_soap_access.conf).

The following example configuration will allow SOAP requests only from "localhost" and IP address "172.16.65.1". Make sure you edit this configuration accordingly to your actual POA environment/network. If you dont know the IP address of the POA host which will use the SOAP interface, contact the POA specialist who is responsible for the project. If you need more fine grained access restrictions see "mod_access" documentation at www.apache.org.

<pre>
<Location /servlet/axis2/services>
Order Deny,Allow
Deny from all
Allow from 172.16.65.1 127.0.0.1
</Location>
</pre>

After you have edited all these properties, please restart „open-xchange" and apache service via init scripts. Now you need to write down the „oxadminmaster“ username and its password which you set up during installation of the normal OX system. Then you should give these credentials and the OX IP/Hostname to the POA specialist. He will enter this infos in the POA environment.

== POA Deployment ==

=== Creating 'External Provisioning' Attribute ===

Create the External Provisioning Attribute.

=== Deploying POA Linux Mail Hosting Module ===

Deploy the POA Linux Mail Hosting Module using the instructions provided in the POA Linux Mail Hosting Deployment Guide.

# The Linux Mail Hosting Module supports the CourierIMAP and Dovecot POP/IMAP Services (the last one is recommended to work with Open-Xchange).
# If you plan to provide to customers the ability to manage the Sieve mail filtering rules through Open-Xchange Control Panel, install the latest version of the dovecot (type: other) POA Package instead of the CourierIMAP (type: other) POA Package. If the existing installation of Linux Mail Hosting Module is used, perform the migration from Courier-IMAP Service to Dovecot POP/IMAP Service. Instructions how to perform the migration are provided in the POA Linux Mail Hosting Deployment Guide, the Deploying Linux Mail Hosting > Migrating from Courier-IMAP Service to Dovecot Service section.
# If you plan to provide to customers the ability to manage the Sieve mail filtering rules through Open-Xchange Control Panel and Clustered QMail Service is used as SMTP/IMAP server for Open-Xchange, add the load balancing rule for TCP port 2000 on Load Balancer. See the POA Linux Mail Hosting Deployment Guide, the Deploying Linux Mail Hosting > Deploying Clustered Qmail Service > Creating Load Balancer section for details.
# It is not required to deploy the IMP and AtMail Webmail Services. 5. The SpamAssassin and DrWeb Services are optional.

==== Create the Resource Types, which are required for Linux Mail Hosting provisioning ====

* CQMail Hosting Resource Type. Use the instructions provided in POA Provider's Guide, the Mail Hosting in POA > Creating 'CQMail Hosting' Resource Type section.
* SpamAssassin Protection. Create the SpamAssassin Protection Resource Type on the basis of the Antispam for mailboxes Resource Class. Instructions on how to do this, are provided in Provider's Guide, the Managing Service Templates > Creating Resource Type section.
* Traffic. Create the Traffic Resource Type on the basis of the Traffic Resource Class. Instructions on how to do this, are provided in Provider's Guide, the Managing Service Templates > Creating Resource Type section.
* Diskspace. Create the Diskspace Resource Type on the basis of the Diskspace Resource Class. Instructions on how to do this, are provided in Provider's Guide, the Managing Service Templates > Creating Resource Type section.

Mark the host where clustered-qmail service is installed as Ready To Provide.

'''Note: Already existing in POA Linux Mail Hosting Module can also be used for deployment.'''

=== Preparing Provisioning Gateway Host ===

* Install php-cgi
* The Application management scripts are contained in the Application package. POA installs Application the management scripts on this host.
* The management scripts provision the Open-Xchange server via http using the SOAP protocol and thus. the Open-Xchange server must be accessible from the provisioning host using these protocols.
* Assign the External Provisioning Attribute to the Provisioning Gateway Host.
* Mark the Provisioning Gateway Host as Ready To Provide.

== POA Configuration ==

=== Import the Application ===

Deploy the application from the [http://www.apsstandard.org/applications#searchterm=open-xchange APS catalogue].

=== APS Package Resource configuration ===

* Click on Add New Resource Type in Top > Service Director > Provisioning Manager > Resource Types.
* Click on the Application Resource class
* Set a name and description
* Select Open-Xchange from the list of applications
* Fill the Global application settings (see below)
* Set the "External Provisioning" attribute

==== Global application settings ====

; Open-Xchange installation host: DNS hostname or ip address of the Open-Xchange provisioning host (will be accessed via SOAP)
; Open-Xchange public site URL: The URL on how to access Open-Xchange Webmail
; Product path to access Open-Xchange: Chose the product path depending on your configuration. On OX App Suite, this is /appsuite/ per default, on OX6, it is /ox6/. Note that the trailing "/" is mandatory.
; Open-Xchange Autologin identifier: Chose either OX App Suite or OX6
; Master Administrator Login: OX provisioning account with rights to create contexts
; Master Administrator Password: Password of provisioning account
; Open-Xchange administrator access level: The access level of the context admin account. Check /opt/open-xchange/etc/ModuleAccessDefinitions.properties for a list of possible values. Should be a permissive value like groupware_premium in order for the admin to be able to manage all features.
; Open-Xchange anti-spam protection interface: It defines whether the spam reporting functionality is enabled. If it is enabled, the Open-Xchange context user is able to mark messages as spam/not spam. Make it enabled. Note that this does not yet work in OX App Suite.
; Public contacts folder: Public folder to place contacts of non Open-Xchange service users into. Not to confuse with the standard public contacts folder in Open-Xchange where every OX mail account is listed.
; Enable data migration from Horde: Enable if you want to migrate data from an existing Horde installation.
; URL to source Horde: Provide URL to Horde Webmail. Will be used only if data migration is enabled in previous setting.
; Service with Connector for Business Mobility:
; Reseller mode: This should be Off in most cases when in use with POA. Makes sense in Plesk deployment, see [[Plesk_Integration]]
; Debug mode: Should be Off per default.

[[Image:New Resource Part 2.png]]

==== Application service "Open-Xchange context" ====

; Open-Xchange context wide filestore quota (in MB): Specify the overall size that can be used to store files in the Open-Xchange context
; Default time zone: Specify the default timezone for new users
; Branding scheme name: The name of the Open-Xchange theme which is applied to the context user. If the parameter is not specified, the default Open-Xchange theme is used.

==== Application service "Webmail Account" ====

; Open-Xchange module access level for Enduser: Specify the access level of a webmail user. Check /opt/open-xchange/etc/ModuleAccessDefinitions.properties for a list of possible values.
; Maximum size of all attachments in one message (in bytes): Specify "0" for unlimited
; Maximum size of one attachment, maximum size of one InfoStore item (in bytes): Specify "0" for unlimited

Note: For an overview of the different supported access levels, see [[OX_Permission_Level]].

===== OX App Suite or OX 6 =====

Depending on whether you plan to integrate OX App Suite or OX 6, you have to select the correct identifier.

[[Image:APS-Identifier.png]]

===== Running OX App Suite and OX 6 in parallel =====

On a parallel setup of OX App Suite and OX6 you may want to access both from you POA. This can be
achieved in creating two resource types in the POA Provisioning Manager. One for OX App Suite and one for
OX 6. In the '''Product path''' setting, you can either specify the path to OX App Suite or to OX6

[[Image:APS-Parallel-OX.png]]

'''Note:''' Do not configure an automatic redirect/url rewrite in this case.

==== Create some Resource Types based on Application Service ====

Now lets create some Resource Types based on Application Service to have something to up-sell.

===== Webmail, PIM and Groupware Resource Types =====

* Click on Add New Resource Type in Top > Service Director > Provisioning Manager > Resource Types
* Chose Application Service
* Fill out name and description

[[Image:Add new Application Resource Part 1.png]]

* Select Open-Xchange Application
* Select Webmail Account

[[Image:Select application service.png]]

* Set Priotity to 1
* Enter webmail as access level

[[Image:Add new Application Resource Part 2.png]]

* Now do the same for PIM and Groupware.
** module access level for PIM is pim
** module access level for Groupware is groupware
** you can chose better maximum sizes for pim and groupware if you want

==== Create a Mobility Resource Type based on Application Service ====

* Click on Add New Resource Type in Top > Service Director > Provisioning Manager > Resource Types
* Chose Application Resource
* Fill out name and description
* Select Open-Xchange Application
* Select Mobile devices support
* Leave Priority empty

[[Image:Select Mobile devices support.png]]

==== Create a Resource Type based on Application Resource ====

* Click on Add New Resource Type in Top > Service Director > Provisioning Manager > Resource Types
* Chose Application Resource
* Fill out name and description
* Select Open-Xchange Application
* Click on ''Disk space used by Open-Xchange context infostore files''

[[Image:Add Application Resource.png]]

At the end, you should have six Resource Types:

[[Image:All Resource Types.png]]

==== Optionally: Remove Mobile devices support from Webmail, PIM and Groupware Resource Types ====

If you don't want to sell Mobile devices support as an extra service, e.g. when it is already part of one of the access levels used in the Resource Types, you can remove it from each of the defined Resource Types. Click on each of these in the Resource Types list, go to Activation Parameters > Services and click on ''Edit''. Uncheck the ''Enable'' checkbox.

[[Image:Remove Mobile Devices Support.png]]

=== Create a Service Template ===

* Click on Add New Service Template in Top > Service Director > Provisioning Manager > Service Templates
* Fill out name and description
* Select Mail Hosting (based on qmail).

[[Image:New Service Template Part1.png]]

* Select a proper Traffic and Diskspace Resource Type

[[Image:New Service Template Part2.png]]

* Now add further Resource Types to the new Service Template

[[Image:Add Resources.png]]

* Find an add all four Resource Types that have been created earlier

[[Image:Add resources Part 2.png]]

* Do not use the Unlimited value for the Open-Xchange Context Diskspace resource. Use the limited values that are large enough. For example: 2 GB, 4 GB, and etc.

[[Image:Resource Limits.png|800px]]

* Finally, you have to activate the Service Template in the General tab

[[Image:Activate Service Template.png]]

Kontakt-Zu-Support

2013-11-07T12:44:48Z

Schweigi: /* Vorgehen: */

Contact-Support

2013-11-07T12:44:15Z

Schweigi: /* Todo: */

Kontakt-Zu-Support

2013-04-23T14:44:55Z

Schweigi:

Contact-Support

2013-04-23T14:43:55Z

Schweigi:

Kontakt-Zu-Support

2013-03-06T08:53:39Z

Schweigi: /* Vorgehen: */